This is an automated email from the ASF dual-hosted git repository. jamesbognar pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/master by this push: new 198b9d5 Javadocs. 198b9d5 is described below commit 198b9d5bf97fb306aa2bf8c3a28bfdd46143dc4a Author: JamesBognar <jamesbog...@apache.org> AuthorDate: Mon Dec 10 20:13:14 2018 -0500 Javadocs. --- .../12.juneau-microservice-jetty/03.Config.html | 139 ------ ...esourceClasses.html => 03.ResourceClasses.html} | 90 +++- ...sses.html => 04.PredefinedResourceClasses.html} | 2 +- .../12.juneau-microservice-jetty/05.Config.html | 221 ++++++++ .../12.juneau-microservice-jetty/06.JettyXml.html | 99 ++++ .../12.juneau-microservice-jetty/07.Extending.html | 64 --- ...iCustomization.html => 07.UiCustomization.html} | 4 +- .../12.juneau-microservice-jetty/08.Extending.html | 90 ++++ .../14.juneau-examples-core/01.Examples.html | 4 +- juneau-doc/src/main/javadoc/overview.html | 553 +++++++++++++++------ juneau-doc/src/main/javadoc/resources/docs.txt | 3 +- .../src/main/javadoc/resources/fragments/toc.html | 11 +- 12 files changed, 914 insertions(+), 366 deletions(-) diff --git a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/03.Config.html b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/03.Config.html deleted file mode 100644 index d4659e1..0000000 --- a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/03.Config.html +++ /dev/null @@ -1,139 +0,0 @@ -<!-- -/*************************************************************************************************************************** - * 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. - ***************************************************************************************************************************/ - --> - -{todo} Config - -<p> - The microservice config file is an external INI-style configuration file that is used to configure - your microservice. -</p> -<h5 class='section'>See Also:</h5> -<ul class='doctree'> - <li class='link'>{@doc juneau-config} -</ul> - - -<p> - There are 3 primary ways of getting access to the config file. -</p> -<ul class='doctree'> - <li class='jm'>{@link oaj.microservice.Microservice#getConfig()} - <br>Any {@doc DefaultRestSvlVariables initialization-time variables} can be used. - <li class='jm'>{@link oajr.RestContext#getConfig()} - <br>Any {@doc DefaultRestSvlVariables initialization-time variables} can be used. - <h5 class='figure'>Example usage:</h5> - <p class='bcode w800'> - <cc>#-------------------------------</cc> - <cc># Properties for MyHelloResource </cc> - <cc>#-------------------------------</cc> - <cs>[MyHelloResource]</cs> - <ck>greeting</ck> = <cv>Hello world!</cv> - </p> - <p class='bcode w800'> - <ja>@RestResource</ja>(...) - <jk>public class</jk> MyHelloResource <jk>extends</jk> BasicRestServlet { - <jc>// Access config file when initializing fields.</jc> - <jk>private</jk> String greeting = getConfig().getString(<js>"MyHelloResource/greeting"</js>); - - <jc>// Or access config file in servlet init method.</jc> - <ja>@Override</ja> <jc>/* Servlet */</jc> - <jk>public void</jk> init() { - String greeting = getConfig().getString(<js>"MyHelloResource/greeting"</js>); - } - } - </p> - <p> - Additional user-defined variables can be defined at this level by adding a - {@link oajr.annotation.HookEvent#INIT} hook method - and using the {@link oajr.RestContextBuilder#vars(Class...)} method. - </p> - <li class='jm'> - {@link oajr.RestRequest#getConfig()} - - An instance method to access it from inside a REST method. - <br>Any {@doc DefaultRestSvlVariables initialization-time or request-time variables} can be used. - - <h5 class='figure'>Example usage:</h5> - <p class='bcode w800'> - <cc>#-----------------------------</cc> - <cc># Contents of microservice.cfg </cc> - <cc>#-----------------------------</cc> - <cs>[MyHelloResource]</cs> - <ck>greeting</ck> = <cv>Hello $RP{person}!</cv> - <ck>localizedGreeting</ck> = <cv>$L{HelloMessage,$RP{person}}</cv> - </p> - <p class='bcode w800'> - <cc>#---------------------------------</cc> - <cc># Contents of MyHelloResource.java </cc> - <cc>#---------------------------------</cc> - <ja>@RestResource</ja>( - path=<js>"/hello"</js>, - messages=<js>"nls/Messages"</js>, - ... - ) - <jk>public class</jk> MyHelloResource <jk>extends</jk> BasicRestServlet { - - <jd>/** Standard hello message. */</jd> - <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/{person}"</js>) - <jk>public</jk> String sayHello(RestRequest req) { - <jk>return</jk> req.getConfig().getString(<js>"MyHelloResource/greeting"</js>); - } - - <jd>/** Hello message in users language. */</jd> - <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/localized/{person}"</js>) - <jk>public</jk> String sayLocalizedHello(RestRequest req) { - <jk>return</jk> req.getConfig().getString(<js>"MyHelloResource/localizedGreeting"</js>); - } - } - </p> - <p class='bcode w800'> - <cc>#---------------------------------------</cc> - <cc># Contents of nls/Messages_en.properties </cc> - <cc>#---------------------------------------</cc> - <ck>MyHelloResource.HelloMessage</ck> = <cv>Hello {0}!</cv> - </p> - <p> - Additional user-defined variables can be defined at this level by overriding the - {@link oajr.RestContextBuilder#vars(Class...)} method. - </p> -</ul> -<p> - That <l>sayLocalizedHello()</l> example might need some explanation since there's a lot going on there. - <br>Here's what happens when an HTTP call is made to <l>GET /hello/localized/Bob</l>: -</p> -<ol class='spaced-list'> - <li> - The HTTP call matches the <l>/hello</l> path on the <l>MyHelloResource</l> class. - <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,$RP{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>. - <li> - The resulting message <l>"Hello Bob!"</l> is returned as a POJO to be serialized to whatever content - type was specified on the <l>Accept</l> header on the request. -</ol> -<p> - This particular example is needlessly complex, but it gives an idea of how variables can be used - recursively to produce sophisticated results -</p> diff --git a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/04.ResourceClasses.html b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/03.ResourceClasses.html similarity index 51% rename from juneau-doc/docs/Topics/12.juneau-microservice-jetty/04.ResourceClasses.html rename to juneau-doc/docs/Topics/12.juneau-microservice-jetty/03.ResourceClasses.html index 2d2b548..1b7a6f7 100644 --- a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/04.ResourceClasses.html +++ b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/03.ResourceClasses.html @@ -13,21 +13,15 @@ ***************************************************************************************************************************/ --> -{todo} Resource Classes +{new} Resource Classes <p> - Now let's take a look at the resource classes themselves. - <br>The top-level page... + This section describes how to define a top-level REST resource page and deploy it in our microservice. + The example is a router page that serves as a jumping off page to child resources. </p> <p class='bpcode w800'> - http://localhost:10000 -</p> -<img class='bordered w800' src='doc-files/juneau-microservice-server.Running.1.png'> -<p> - ...is generated by this class... -<p class='bpcode w800'> <ja>@RestResource</ja>( - path=<js>"/"</js>, + path=<js>"/*"</js>, title=<js>"My Microservice"</js>, description=<js>"Top-level resources page"</js>, htmldoc=<ja>@HtmlDoc</ja>( @@ -45,6 +39,13 @@ <jc>// No code! </jc> } </p> +<p> + When deployed, it looks like this in a browser: +</p> +<p class='bpcode w800'> + http://localhost:10000 +</p> +<img class='bordered w800' src='doc-files/juneau-microservice-server.Running.1.png'> <ul class='spaced-list'> <li> The </l>title</l> and <l>description</l> annotations define the titles on the page. @@ -83,3 +84,72 @@ } } </p> +<p> + The most-common case for deploying the top-level resource is to use the {@link oaj.microservice.jetty.JettyMicroserviceBuilder#servlet(Class)} method: +</p> +<p class='bpcode w800'> + <jk>public class</jk> App { + <jk>public static void</jk> main(String[] args) { + JettyMicroservice + .<jsm>create</jsm>() + .args(args) + .servlet(RootResources.<jk>class</jk>) <jc>// Our root resource.</jc> + .build() + .start() + ; + } + } +</p> +<p> + However, there are multiple ways of deploying top-level resources: +</p> +<ul class='spaced-list'> + <li> + {@link oaj.microservice.jetty.JettyMicroserviceBuilder#servlet(Class)} - Using the builder. Several methods provided. + <li> + {@link oaj.microservice.jetty.JettyMicroservice#addServlet(Servlet,String)} - After the Jetty container has been started. + <li> + As a configuration variable <js>"Jetty/servlets"</js>. + <p class='bcode w800'> + <cc>#======================================================================================================================= + # Jetty settings + #=======================================================================================================================</cc> + <cs>[Jetty]</cs> + + <cc># Subclasses of RestServlet</cc> + <ck>servlets</ck> = <cv>org.apache.juneau.examples.rest.RootResources</cv> + </p> + <li> + As a configuration variable <js>"Jetty/servletMap"</js>. + <p class='bcode w800'> + <cc>#======================================================================================================================= + # Jetty settings + #=======================================================================================================================</cc> + <cs>[Jetty]</cs> + + <cc># Any servlets and their path specs</cc> + <ck>servletMap</ck> = + <cv>{ + '/*': 'org.apache.juneau.examples.rest.RootResources' + }</cv> + </cv> + <li> + Directly in the <code>jetty.xml</code> file. + <p class='bcode w800'> + <xt><Configure</xt> <xa>id</xa>=<xs>"ExampleServer"</xs> <xa>class</xa>=<xs>"org.eclipse.jetty.server.Server"</xs><xt>></xt> + ... + <xt><New</xt> <xa>id</xa>=<xs>"context"</xs> <xa>class</xa>=<xs>"org.eclipse.jetty.servlet.ServletContextHandler"</xs><xt>></xt> + <xt><Set</xt> <xa>name</xa>=<xs>"contextPath"</xs><xt>>/</Set></xt> + <xt><Call</xt> <xa>name</xa>=<xs>"addServlet"</xs><xt>></xt> + <xt><Arg></xt>org.apache.juneau.rest.test.Root<xt></Arg></xt> + <xt><Arg></xt>/*<xt></Arg></xt> + <xt></Call></xt> + <xt><Set</xt> <xa>name</xa>=<xs>"sessionHandler"</xs><xt>></xt> + <xt><New</xt> <xa>class</xa>=<xs>"org.eclipse.jetty.server.session.SessionHandler"</xs> <xt>/></xt> + <xt></Set></xt> + <xt></New></xt> + ... + </p> +</ul> + + diff --git a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/05.PredefinedResourceClasses.html b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/04.PredefinedResourceClasses.html similarity index 98% rename from juneau-doc/docs/Topics/12.juneau-microservice-jetty/05.PredefinedResourceClasses.html rename to juneau-doc/docs/Topics/12.juneau-microservice-jetty/04.PredefinedResourceClasses.html index cd6dea2..af6c1d0 100644 --- a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/05.PredefinedResourceClasses.html +++ b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/04.PredefinedResourceClasses.html @@ -13,7 +13,7 @@ ***************************************************************************************************************************/ --> -{todo} Predefined Resource Classes +{new} Predefined Resource Classes <p> The following predefined resource classes are also provided for easy inclusion into your microservice: diff --git a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/05.Config.html b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/05.Config.html new file mode 100644 index 0000000..f88431e --- /dev/null +++ b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/05.Config.html @@ -0,0 +1,221 @@ +<!-- +/*************************************************************************************************************************** + * 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. + ***************************************************************************************************************************/ + --> + +{new} Config + +<p> + In {@doc juneau-microservice-core.Config}, we described how to associate a configuration file with your + microservice. + In this section we describe how that configuration can be used to customize the behavior or your REST resource + classes. +</p> +<p> + The most common usage for the configuration file is to reference values using the {@link oaj.config.vars.ConfigVar $C} variable in annotations. + For example, the {@link oajr.BasicRestConfig} interface that defines the annotations that control the look-and-feel of + classes that extend from {@link oajr.BasicRestServlet} use several <code>$C</code> variables to externalize values: +</p> +<p class='bpcode w800'> + <ja>@RestResource</ja>( + ... + + <jc>// HTML-page specific settings</jc> + htmldoc=<ja>@HtmlDoc</ja>( + + <jc>// Default page header contents.</jc> + header={ + <js>"<h1>$R{resourceTitle}</h1>"</js>, <jc>// Use @RestResource(title)</jc> + <js>"<h2>$R{methodSummary,resourceDescription}</h2>"</js>, <jc>// Use either @RestMethod(summary) or @RestResource(description)</jc> + <js>"$C{REST/header}"</js> <jc>// Extra header HTML defined in external config file.</jc> + }, + + <jc>// Default stylesheet to use for the page. + // Can be overridden from external config file. + // Default is DevOps look-and-feel (aka Depression look-and-feel).</jc> + stylesheet=<js>"$C{REST/theme,servlet:/htdocs/themes/devops.css}"</js>, + + <jc>// Default contents to add to the <head> section of the HTML page. + // Use it to add a favicon link to the page.</jc> + head={ + <js>"<link rel='icon' href='$U{$C{REST/favicon}}'/>"</js> + }, + + <jc>// No default page footer contents. + // Can be overridden from external config file.</jc> + footer=<js>"$C{REST/footer}"</js>, + ... + ), + + <jc>// These are static files that are served up by the servlet under the specified sub-paths. + // For example, "/servletPath/htdocs/javadoc.css" resolves to the file "[servlet-package]/htdocs/javadoc.css" + // By default, we define static files through the external configuration file.</jc> + staticFiles=<js>"$C{REST/staticFiles}"</js> + ) + <jk>public interface</jk> BasicRestConfig {} +</p> +<p> + These values in turn are pulled from the external configuration file shown below. + Note that the configuration file can also contain <code>$C</code> variables. +</p> +<p class='bpcode w800'> + <cc>#======================================================================================================================= + # REST settings + #=======================================================================================================================</cc> + <cs>[REST]</cs> + + <cc># Mappings to folders containing static files.</cc> + <cc># Can be in the working directory or in the classpath.</cc> + <ck>staticFiles</ck> = <cv>htdocs:files/htdocs</cv> + + <cc># Stylesheet to use for HTML views.</cc> + <ck>theme</ck> = <cv>servlet:/htdocs/themes/devops.css</cv> + + <ck>headerIcon</ck> = <cv>servlet:/htdocs/images/juneau.png</cv> + <ck>headerLink</ck> = <cv>http://juneau.apache.org</cv> + <ck>footerIcon</ck> = <cv>servlet:/htdocs/images/asf.png</cv> + <ck>footerLink</ck> = <cv>http://www.apache.org</cv> + + <ck>favicon</ck> = <cv>$C{REST/headerIcon}</cv> + <ck>header</ck> = + <cv><a href='$U{$C{REST/headerLink}}'></cv> + <cv><img src='$U{$C{REST/headerIcon}}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/></cv> + <cv></a></cv> + <ck>footer</ck> = + <cv><a href='$U{$C{REST/footerLink}}'></cv> + <cv><img src='$U{$C{REST/footerIcon}}' style='float:right;padding-right:20px;height:32px'/></cv> + <cv></a></cv> +</p> + +<p> + Configuration files can also be accessed programmatically. + There are 3 primary ways of getting access to the config file: +</p> +<ul class='doctree'> + <li class='jm'>{@link oaj.microservice.Microservice#getConfig()} + <p>Any {@doc DefaultRestSvlVariables initialization-time variables} can be used.</p> + <li class='jm'>{@link oajr.RestContext#getConfig()} + <p>Any {@doc DefaultRestSvlVariables initialization-time variables} can be used.</p> + <h5 class='figure'>Example usage:</h5> + <p class='bcode w800'> + <cc>#----------------------------------</cc> + <cc># Configuration for MyHelloResource </cc> + <cc>#----------------------------------</cc> + <cs>[MyHelloResource]</cs> + <ck>greeting</ck> = <cv>Hello world!</cv> + </p> + <p class='bcode w800'> + <cc>#---------------------------------</cc> + <cc># Contents of MyHelloResource.java </cc> + <cc>#---------------------------------</cc> + <ja>@RestResource</ja>(...) + <jk>public class</jk> MyHelloResource <jk>extends</jk> BasicRestServlet { + <jk>private</jk> String <jf>greeting</jf>; + + <jc>// Or access config file in servlet init method.</jc> + <ja>@Override</ja> <jc>/* Servlet */</jc> + <jk>public void</jk> init() { + Config c = getContext().getConfig(); + <jk>this</jk>.<jf>greeting</jf> = c.getString(<js>"MyHelloResource/greeting"</js>); + } + } + </p> + <p> + Additional user-defined variables at the servlet level can be defined by adding a + {@link oajr.annotation.HookEvent#INIT} hook method + and using the {@link oajr.RestContextBuilder#vars(Class...)} method. + </p> + <li class='jm'> + {@link oajr.RestRequest#getConfig()} + - An instance method to access it from inside a REST method. + <p>Any {@doc DefaultRestSvlVariables initialization-time or request-time variables} can be used.</p> + + <h5 class='figure'>Example usage:</h5> + <p class='bcode w800'> + <cc>#----------------------------------</cc> + <cc># Configuration for MyHelloResource</cc> + <cc>#----------------------------------</cc> + <cs>[MyHelloResource]</cs> + <ck>greeting</ck> = <cv>Hello $RP{person}!</cv> <cc>// $RP is RequestPathVar</cc> + <ck>localizedGreeting</ck> = <cv>$L{HelloMessage,$RP{person}}</cv> <cc>// $L is LocalizationVar with args</cc> + </p> + <p class='bcode w800'> + <cc>#---------------------------------</cc> + <cc># Contents of MyHelloResource.java </cc> + <cc>#---------------------------------</cc> + <ja>@RestResource</ja>( + path=<js>"/hello"</js>, + messages=<js>"nls/Messages"</js>, + ... + ) + <jk>public class</jk> MyHelloResource <jk>extends</jk> BasicRestServlet { + + <jd>/** Standard hello message. */</jd> + <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/{person}"</js>) + <jk>public</jk> String sayHello(RestRequest req) { + <jk>return</jk> req.getConfig().getString(<js>"MyHelloResource/greeting"</js>); + } + + <jd>/** Hello message in users language. */</jd> + <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/localized/{person}"</js>) + <jk>public</jk> String sayLocalizedHello(RestRequest req) { + <jk>return</jk> req.getConfig().getString(<js>"MyHelloResource/localizedGreeting"</js>); + } + } + </p> + <p class='bcode w800'> + <cc>#---------------------------------------</cc> + <cc># Contents of nls/Messages_en.properties </cc> + <cc>#---------------------------------------</cc> + <ck>MyHelloResource.HelloMessage</ck> = <cv>Hello {0}!</cv> + </p> + <p> + Additional user-defined variables can be defined at this level by overriding the + {@link oajr.RestContextBuilder#vars(Class...)} method. + </p> +</ul> +<p> + That <l>sayLocalizedHello()</l> example might need some explanation since there's a lot going on there. + <br>Here's what happens when an HTTP call is made to <l>GET /hello/localized/Bob</l>: +</p> +<ol class='spaced-list'> + <li> + The HTTP call matches the <l>/hello</l> path on the <l>MyHelloResource</l> class. + <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,$RP{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>. + <li> + The resulting message <l>"Hello Bob!"</l> is returned as a POJO to be serialized to whatever content + type was specified on the <l>Accept</l> header on the request. +</ol> +<p> + This particular example is needlessly complex, but it gives an idea of how variables can be used + recursively to produce sophisticated results +</p> + +<h5 class='section'>See Also:</h5> +<ul class='doctree'> + <li class='link'>{@doc juneau-config} +</ul> + diff --git a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/06.JettyXml.html b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/06.JettyXml.html new file mode 100644 index 0000000..fd23bdc --- /dev/null +++ b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/06.JettyXml.html @@ -0,0 +1,99 @@ +<!-- +/*************************************************************************************************************************** + * 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. + ***************************************************************************************************************************/ + --> + +{new} Jetty.xml file + +<p> + The Jetty microservice comes with a bare-bones <code>jetty.xml</code> file which can be modified to suite any needs. +</p> +<p> + The <code>jetty.xml</code> can be located in either the <js>"."</js> or <js>"files"</js> working directory or classpath. + It can also be specified in any of the following ways: +</p> +<ul class='spaced-list'> + <li> + Using the {@link oaj.microservice.jetty.JettyMicroserviceBuilder#jettyXml(Object,boolean)} method to specify the location or contents + of the file. + <li> + Specifying the location using a <code>Jetty-Config</code> value in the <code>MANIFEST.MF</code> file. + <p class='bcode w800'> + <mk>Jetty-Config:</mk> <mv>files/jetty.xml</mv> + </p> + <li> + Specifying the location using the <js>"Jetty/jettyXml"</js> configuration value. + <p class='bcode w800'> + <cc>#======================================================================================================================= + # Jetty settings + #=======================================================================================================================</cc> + <cs>[Jetty]</cs> + + <cc># Path of the jetty.xml file used to configure the Jetty server.</cc> + <ck>config</ck> = <cv>files/jetty.xml</cv> + </p> +</ul> +<p> + SVL variables in the <code>jetty.xml</code> file are automatically resolved by the microservice. + This allows you to reference values in your configuration file from the <code>jetty.xml</code> file. +</p> +<p> + The HTTP port used is controlled via the following: +</p> +<ul class='spaced-list'> + <li> + The {@link oaj.microservice.jetty.JettyMicroserviceBuilder#ports(int...)} method. + <p class='bcode w800'> + JettyMicroservice + .<jsm>create</jsm>() + .args(args) + .servlets(RootResource.<jk>class</jk>) + .port(1000,2000,0,0,0) <jc>// Try port 1000, then 2000, then 3 random ports.</jc> + .build() + .start() + </p> + <li> + The <js>"Jetty/ports"</js> configuration property. + <p class='bcode w800'> + <cc>#======================================================================================================================= + # Jetty settings + #=======================================================================================================================</cc> + <cs>[Jetty]</cs> + + <cc># Port to use for the jetty server. + # You can specify multiple ports. The first available will be used. '0' indicates to try a random port. + <ck>port</ck> = <cv>1000,2000,0,0,0</cv> + </p> +</ul> +<p> + The first available port is then made available through the system property <js>"availablePort"</js> so that it + can be referenced in our <code>jetty.xml</code> file. +</p> +<p class='bpcode w800'> + <xt><Set</xt> <xa>name</xa>=<xs>"connectors"</xs><xt>></xt> + <xt><Array</xt> <xa>type</xa>=<xs>"org.eclipse.jetty.server.Connector"</xs><xt>></xt> + <xt><Item></xt> + <xt><New</xt> <xa>class</xa>=<xs>"org.eclipse.jetty.server.ServerConnector"</xs><xt>></xt> + <xt><Arg></xt> + <xt><Ref</xt> <xa>refid</xa>=<xs>"ExampleServer"</xs> <xt>/></xt> + <xt></Arg></xt> + <xt><Set</xt> <xa>name</xa>=<xs>"port"</xs><xt>></xt>$S{availablePort,8080}<xt></Set></xt> + <xt></New></xt> + <xt></Item></xt> + <xt></Array></xt> + <xt></Set></xt> +</p> +<p> + The {@link oaj.microservice.jetty.JettyMicroserviceBuilder#jettyServerFactory(JettyServerFactory)} method is also provided + to use your own customized Jetty server. +</p> diff --git a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/07.Extending.html b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/07.Extending.html deleted file mode 100644 index 5ceef27..0000000 --- a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/07.Extending.html +++ /dev/null @@ -1,64 +0,0 @@ -<!-- -/*************************************************************************************************************************** - * 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. - ***************************************************************************************************************************/ - --> - -Extending RestMicroservice - -<p> - This example shows how the {@link oaj.microservice.RestMicroservice} class - can be extended to implement lifecycle listener methods or override existing methods. - <br>We'll create a new class <l>com.foo.SampleCustomRestMicroservice</l>. -</p> -<p> - First, the manifest file needs to be modified to point to our new microservice: -</p> -<p class='bpcode w800'> - <mk>Main-Class:</mk> com.foo.SampleCustomRestMicroservice -</p> -<p> - Then we define the following class: -</p> -<p class='bpcode w800'> - <jd>/** - * Sample subclass of a RestMicroservice that provides customized behavior. - * This class must be specified in the Main-Class entry in the manifest file and optionally - * a Main-ConfigFile entry. - */</jd> - <jk>public class</jk> SampleCustomRestMicroservice <jk>extends</jk> RestMicroservice { - - <jd>/** - * Must implement a main method and call start()! - */</jd> - <jk>public static void</jk> main(String[] args) <jk>throws</jk> Exception { - <jk>new</jk> SampleCustomRestMicroservice(args).start().join(); - } - - <jd>/** - * Must implement a constructor! - * - * <ja>@param</ja> args Command line arguments. - * <ja>@throws</ja> Exception - */</jd> - <jk>public</jk> SampleCustomRestMicroservice(String[] args) <jk>throws</jk> Exception { - <jk>super</jk>(args); - } -</p> -<p> - The microservice APIs provide several useful methods that can be used or extended. -</p> -<h5 class='section'>See Also:</h5> -<ul class='doctree'> - <li class='jac'>{@link oaj.microservice.Microservice} - <li class='jc'>{@link oaj.microservice.RestMicroservice} -</ul> diff --git a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/06.UiCustomization.html b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/07.UiCustomization.html similarity index 97% rename from juneau-doc/docs/Topics/12.juneau-microservice-jetty/06.UiCustomization.html rename to juneau-doc/docs/Topics/12.juneau-microservice-jetty/07.UiCustomization.html index f31d2be..acf5ba4 100644 --- a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/06.UiCustomization.html +++ b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/07.UiCustomization.html @@ -13,10 +13,10 @@ ***************************************************************************************************************************/ --> -{todo} UI Customization +{new} UI Customization <p> - The Microservice project contains a <code>files/htdocs</code> working directly folder with predefined stylesheets and + The Microservice project contains a <code>files/htdocs</code> folder with predefined stylesheets and images. </p> <img style='width:200px' src='doc-files/juneau-microservice.UiCustomization.1.png'> diff --git a/juneau-doc/docs/Topics/12.juneau-microservice-jetty/08.Extending.html b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/08.Extending.html new file mode 100644 index 0000000..711acd5 --- /dev/null +++ b/juneau-doc/docs/Topics/12.juneau-microservice-jetty/08.Extending.html @@ -0,0 +1,90 @@ +<!-- +/*************************************************************************************************************************** + * 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. + ***************************************************************************************************************************/ + --> + +{new} Extending JettyMicroservice + +<p> + This example shows how the {@link oaj.microservice.jetty.JettyMicroservice} class + can be extended to implement lifecycle listener methods or override existing methods. + <br>We'll create a new class <l>com.foo.MyJettyMicroservice</l>. +</p> +<p class='bpcode w800'> + <jd>/** + * Sample subclass of a JettyMicroservice that provides customized behavior. + */</jd> + <jk>public class</jk> MyJettyMicroservice <jk>extends</jk> JettyMicroservice { + + <jk>public static void</jk> main(String[] args) <jk>throws</jk> Exception { + JettyMicroserviceBuilder builder = JettyMicroservice.<jsm>create</jsm>(); + <jk>new</jk> MyJettyMicroservice(builder).start().join(); + } + + <jk>public</jk> MyJettyMicroservice(JettyMicroserviceBuilder builder) <jk>throws</jk> Exception { + <jk>super</jk>(builder); + } + + <jc>// Customized code here.</jc> +</p> +<p> + Optionally, you can extend the {@link oaj.microservice.jetty.JettyMicroserviceBuilder} class as well: +</p> +<p class='bpcode w800'> + <jk>public class</jk> MyJettyMicroserviceBuilder <jk>extends</jk> JettyMicroserviceBuilder { + + <jk>int</jk> <jf>extraField</jf>; + + <jd>/** + * Constructor (required). + */</jd> + <jk>protected</jk> MyJettyMicroserviceBuilder() {} + + <jd>/** + * Copy constructor (required). + * + * <ja>@param</ja> copyFrom The builder to copy settings from. + */</jd> + <jk>protected</jk> MyJettyMicroserviceBuilder(MyJettyMicroserviceBuilder copyFrom) { + <jk>super</jk>(copyFrom); + } + + <jc>// Additional setters</jc> + + <jk>public</jk> MyJettyMicroserviceBuilder extraField(<jk>int</jk> extraField) { + <jk>this</jk>.<jf>extraField</jf> = extraField; + <jk>return this</jk>; + } + + <jc>// Overridden methods</jc> + + <ja>@Override</ja> <jc>/* JettyMicroserviceBuilder */</jc> + <jk>public</jk> MyJettyMicroserviceBuilder copy() { + <jk>return new</jk> MyJettyMicroserviceBuilder(<jk>this</jk>); + } + + <ja>@Override</ja> <jc>/* JettyMicroserviceBuilder */</jc> + <jk>public</jk> MyJettyMicroserviceBuilder ports(<jk>int</jk>...ports) { + <jk>super</jk>.ports(ports); + <jk>return this</jk>; + } + + <ja>@Override</ja> <jc>/* JettyMicroserviceBuilder */</jc> + <jk>public</jk> MyJettyMicroserviceBuilder servlet(Class<? <jk>extends</jk> RestServlet> c) <jk>throws</jk> InstantiationException, IllegalAccessException { + <jk>super</jk>.servlet(c); + <jk>return this</jk>; + } + + ... + } +</p> diff --git a/juneau-doc/docs/Topics/14.juneau-examples-core/01.Examples.html b/juneau-doc/docs/Topics/14.juneau-examples-core/01.Examples.html index 5a421d5..2709848 100644 --- a/juneau-doc/docs/Topics/14.juneau-examples-core/01.Examples.html +++ b/juneau-doc/docs/Topics/14.juneau-examples-core/01.Examples.html @@ -37,7 +37,7 @@ </ul> <li class='jp'><code>org.apache.juneau.examples.core.html</code> <ul> - <li class='jc'>{@link oaj.examples.core.core.HtmlSimpleExample} - Htmlerializer usage on serialize simple Pojo bean. - <li class='jc'>{@link oaj.examples.core.core.HtmlCompexExample} - HtmlSerializer usage on serialize complex Pojo bean. + <li class='jc'>{@link oaj.examples.core.html.HtmlSimpleExample} - HtmlSerializer usage on serialize simple Pojo bean. + <li class='jc'>{@link oaj.examples.core.html.HtmlComplexExample} - HtmlSerializer usage on serialize complex Pojo bean. </ul> </ul> diff --git a/juneau-doc/src/main/javadoc/overview.html b/juneau-doc/src/main/javadoc/overview.html index ffddc04..ba7f7bb 100644 --- a/juneau-doc/src/main/javadoc/overview.html +++ b/juneau-doc/src/main/javadoc/overview.html @@ -410,11 +410,12 @@ <ol> <li><p class='new'><a class='doclink' href='#juneau-microservice-jetty.Overview'>Overview</a></p> <li><p class='new'><a class='doclink' href='#juneau-microservice-jetty.LifecycleMethods'>Lifecycle Methods</a></p> - <li><p class='todo'><a class='doclink' href='#juneau-microservice-jetty.Config'>Config</a></p> - <li><p class='todo'><a class='doclink' href='#juneau-microservice-jetty.ResourceClasses'>Resource Classes</a></p> - <li><p class='todo'><a class='doclink' href='#juneau-microservice-jetty.PredefinedResourceClasses'>Predefined Resource Classes</a></p> - <li><p class='todo'><a class='doclink' href='#juneau-microservice-jetty.UiCustomization'>UI Customization</a></p> - <li><p class=''><a class='doclink' href='#juneau-microservice-jetty.Extending'>Extending RestMicroservice</a></p> + <li><p class='new'><a class='doclink' href='#juneau-microservice-jetty.ResourceClasses'>Resource Classes</a></p> + <li><p class='new'><a class='doclink' href='#juneau-microservice-jetty.PredefinedResourceClasses'>Predefined Resource Classes</a></p> + <li><p class='new'><a class='doclink' href='#juneau-microservice-jetty.Config'>Config</a></p> + <li><p class='new'><a class='doclink' href='#juneau-microservice-jetty.JettyXml'>Jetty.xml file</a></p> + <li><p class='new'><a class='doclink' href='#juneau-microservice-jetty.UiCustomization'>UI Customization</a></p> + <li><p class='new'><a class='doclink' href='#juneau-microservice-jetty.Extending'>Extending JettyMicroservice</a></p> </ol> <li><p class='toc2 todo'><a class='doclink' href='#juneau-microservice-jetty-template'>juneau-microservice-jetty-template</a></p> <ol> @@ -24460,65 +24461,304 @@ <!-- ==================================================================================================== --> -<h3 class='topic todo' onclick='toggle(this)'><a href='#juneau-microservice-jetty.Config' id='juneau-microservice-jetty.Config'>12.3 - Config</a></h3> -<div class='topic'><!-- START: 12.3 - juneau-microservice-jetty.Config --> +<h3 class='topic new' onclick='toggle(this)'><a href='#juneau-microservice-jetty.ResourceClasses' id='juneau-microservice-jetty.ResourceClasses'>12.3 - Resource Classes</a></h3> +<div class='topic'><!-- START: 12.3 - juneau-microservice-jetty.ResourceClasses --> <p> - The microservice config file is an external INI-style configuration file that is used to configure - your microservice. + This section describes how to define a top-level REST resource page and deploy it in our microservice. + The example is a router page that serves as a jumping off page to child resources. +</p> +<p class='bpcode w800'> + <ja>@RestResource</ja>( + path=<js>"/*"</js>, + title=<js>"My Microservice"</js>, + description=<js>"Top-level resources page"</js>, + htmldoc=<ja>@HtmlDoc</ja>( + navlinks={ + <js>"options: servlet:/?method=OPTIONS"</js> + } + ), + children={ + HelloWorldResource.<jk>class</jk>, + ConfigResource.<jk>class</jk>, + LogsResource.<jk>class</jk> + } + ) + <jk>public class</jk> RootResources <jk>extends</jk> BasicRestServletJenaGroup { + <jc>// No code! </jc> + } +</p> +<p> + When deployed, it looks like this in a browser: +</p> +<p class='bpcode w800'> + http://localhost:10000 +</p> +<img class='bordered w800' src='doc-files/juneau-microservice-server.Running.1.png'> +<ul class='spaced-list'> + <li> + The </l>title</l> and <l>description</l> annotations define the titles on the page. + <br>These can be globalized using <l>$L{...}</l> variables, or by defining specially-named properties in the + properties file for the resource. + <li> + In this case, the <l>path</l> annotation defines the context root of your application since it was + not specified in the manifest or config file. + <br>Therefore, this resource is mapped to <l>http://localhost:10000</l>. + <li> + The <l>children</l> annotation make up the list of child resources. + <br>These child resources can be anything that extends from <l>Servlet</l>, although usually + they will be subclasses of {@link org.apache.juneau.rest.BasicRestServlet} or other resource groups. +</ul> +<p> + If you click the <l>helloWorld</l> link in your application, you'll get a simple hello world message: +</p> +<p class='bpcode w800'> + http://localhost:10000/helloWorld +</p> +<img class='bordered w800' src='doc-files/juneau-microservice-server.ResourceClasses.1.png'> +<p> + ...which is generated by this class... +</p> +<p class='bpcode w800'> + <ja>@RestResource</ja>( + path=<js>"/helloWorld"</js>, + title=<js>"Hello World example"</js>, + description=<js>"Simplest possible REST resource"</js> + ) + <jk>public class</jk> HelloWorldResource <jk>extends</jk> BasicRestServlet { + + <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/*"</js>) + <jk>public</jk> String sayHello() { + <jk>return</jk> <js>"Hello world!"</js>; + } + } +</p> +<p> + The most-common case for deploying the top-level resource is to use the {@link org.apache.juneau.microservice.jetty.JettyMicroserviceBuilder#servlet(Class)} method: +</p> +<p class='bpcode w800'> + <jk>public class</jk> App { + <jk>public static void</jk> main(String[] args) { + JettyMicroservice + .<jsm>create</jsm>() + .args(args) + .servlet(RootResources.<jk>class</jk>) <jc>// Our root resource.</jc> + .build() + .start() + ; + } + } +</p> +<p> + However, there are multiple ways of deploying top-level resources: +</p> +<ul class='spaced-list'> + <li> + {@link org.apache.juneau.microservice.jetty.JettyMicroserviceBuilder#servlet(Class)} - Using the builder. Several methods provided. + <li> + {@link org.apache.juneau.microservice.jetty.JettyMicroservice#addServlet(Servlet,String)} - After the Jetty container has been started. + <li> + As a configuration variable <js>"Jetty/servlets"</js>. + <p class='bcode w800'> + <cc>#======================================================================================================================= + # Jetty settings + #=======================================================================================================================</cc> + <cs>[Jetty]</cs> + + <cc># Subclasses of RestServlet</cc> + <ck>servlets</ck> = <cv>org.apache.juneau.examples.rest.RootResources</cv> + </p> + <li> + As a configuration variable <js>"Jetty/servletMap"</js>. + <p class='bcode w800'> + <cc>#======================================================================================================================= + # Jetty settings + #=======================================================================================================================</cc> + <cs>[Jetty]</cs> + + <cc># Any servlets and their path specs</cc> + <ck>servletMap</ck> = + <cv>{ + '/*': 'org.apache.juneau.examples.rest.RootResources' + }</cv> + </cv> + <li> + Directly in the <code>jetty.xml</code> file. + <p class='bcode w800'> + <xt><Configure</xt> <xa>id</xa>=<xs>"ExampleServer"</xs> <xa>class</xa>=<xs>"org.eclipse.jetty.server.Server"</xs><xt>></xt> + ... + <xt><New</xt> <xa>id</xa>=<xs>"context"</xs> <xa>class</xa>=<xs>"org.eclipse.jetty.servlet.ServletContextHandler"</xs><xt>></xt> + <xt><Set</xt> <xa>name</xa>=<xs>"contextPath"</xs><xt>>/</Set></xt> + <xt><Call</xt> <xa>name</xa>=<xs>"addServlet"</xs><xt>></xt> + <xt><Arg></xt>org.apache.juneau.rest.test.Root<xt></Arg></xt> + <xt><Arg></xt>/*<xt></Arg></xt> + <xt></Call></xt> + <xt><Set</xt> <xa>name</xa>=<xs>"sessionHandler"</xs><xt>></xt> + <xt><New</xt> <xa>class</xa>=<xs>"org.eclipse.jetty.server.session.SessionHandler"</xs> <xt>/></xt> + <xt></Set></xt> + <xt></New></xt> + ... + </p> +</ul> +</div><!-- END: 12.3 - juneau-microservice-jetty.ResourceClasses --> + +<!-- ==================================================================================================== --> + +<h3 class='topic new' onclick='toggle(this)'><a href='#juneau-microservice-jetty.PredefinedResourceClasses' id='juneau-microservice-jetty.PredefinedResourceClasses'>12.4 - Predefined Resource Classes</a></h3> +<div class='topic'><!-- START: 12.4 - juneau-microservice-jetty.PredefinedResourceClasses --> +<p> + The following predefined resource classes are also provided for easy inclusion into your microservice: </p> -<h5 class='section'>See Also:</h5> <ul class='doctree'> - <li class='link'>{@doc juneau-config} + <li class='jc'>{@link org.apache.juneau.microservice.resources.ConfigResource} + - View and modify the external INI config file. + <li class='jc'>{@link org.apache.juneau.microservice.resources.DirectoryResource} + - View and modify file system directories. + <li class='jc'>{@link org.apache.juneau.microservice.resources.LogsResource} + - View and control generated log files. + <li class='jc'>{@link org.apache.juneau.microservice.resources.SampleRootResource} + - A sample root resource class to get started from. + <li class='jc'>{@link org.apache.juneau.microservice.resources.ShutdownResource} + - Shutdown and/or restart the JVM. </ul> +</div><!-- END: 12.4 - juneau-microservice-jetty.PredefinedResourceClasses --> +<!-- ==================================================================================================== --> +<h3 class='topic new' onclick='toggle(this)'><a href='#juneau-microservice-jetty.Config' id='juneau-microservice-jetty.Config'>12.5 - Config</a></h3> +<div class='topic'><!-- START: 12.5 - juneau-microservice-jetty.Config --> <p> - There are 3 primary ways of getting access to the config file. + In {@doc juneau-microservice-core.Config}, we described how to associate a configuration file with your + microservice. + In this section we describe how that configuration can be used to customize the behavior or your REST resource + classes. +</p> +<p> + The most common usage for the configuration file is to reference values using the {@link org.apache.juneau.config.vars.ConfigVar $C} variable in annotations. + For example, the {@link org.apache.juneau.rest.BasicRestConfig} interface that defines the annotations that control the look-and-feel of + classes that extend from {@link org.apache.juneau.rest.BasicRestServlet} use several <code>$C</code> variables to externalize values: +</p> +<p class='bpcode w800'> + <ja>@RestResource</ja>( + ... + + <jc>// HTML-page specific settings</jc> + htmldoc=<ja>@HtmlDoc</ja>( + + <jc>// Default page header contents.</jc> + header={ + <js>"<h1>$R{resourceTitle}</h1>"</js>, <jc>// Use @RestResource(title)</jc> + <js>"<h2>$R{methodSummary,resourceDescription}</h2>"</js>, <jc>// Use either @RestMethod(summary) or @RestResource(description)</jc> + <js>"$C{REST/header}"</js> <jc>// Extra header HTML defined in external config file.</jc> + }, + + <jc>// Default stylesheet to use for the page. + // Can be overridden from external config file. + // Default is DevOps look-and-feel (aka Depression look-and-feel).</jc> + stylesheet=<js>"$C{REST/theme,servlet:/htdocs/themes/devops.css}"</js>, + + <jc>// Default contents to add to the <head> section of the HTML page. + // Use it to add a favicon link to the page.</jc> + head={ + <js>"<link rel='icon' href='$U{$C{REST/favicon}}'/>"</js> + }, + + <jc>// No default page footer contents. + // Can be overridden from external config file.</jc> + footer=<js>"$C{REST/footer}"</js>, + ... + ), + + <jc>// These are static files that are served up by the servlet under the specified sub-paths. + // For example, "/servletPath/htdocs/javadoc.css" resolves to the file "[servlet-package]/htdocs/javadoc.css" + // By default, we define static files through the external configuration file.</jc> + staticFiles=<js>"$C{REST/staticFiles}"</js> + ) + <jk>public interface</jk> BasicRestConfig {} +</p> +<p> + These values in turn are pulled from the external configuration file shown below. + Note that the configuration file can also contain <code>$C</code> variables. +</p> +<p class='bpcode w800'> + <cc>#======================================================================================================================= + # REST settings + #=======================================================================================================================</cc> + <cs>[REST]</cs> + + <cc># Mappings to folders containing static files.</cc> + <cc># Can be in the working directory or in the classpath.</cc> + <ck>staticFiles</ck> = <cv>htdocs:files/htdocs</cv> + + <cc># Stylesheet to use for HTML views.</cc> + <ck>theme</ck> = <cv>servlet:/htdocs/themes/devops.css</cv> + + <ck>headerIcon</ck> = <cv>servlet:/htdocs/images/juneau.png</cv> + <ck>headerLink</ck> = <cv>http://juneau.apache.org</cv> + <ck>footerIcon</ck> = <cv>servlet:/htdocs/images/asf.png</cv> + <ck>footerLink</ck> = <cv>http://www.apache.org</cv> + + <ck>favicon</ck> = <cv>$C{REST/headerIcon}</cv> + <ck>header</ck> = + <cv><a href='$U{$C{REST/headerLink}}'></cv> + <cv><img src='$U{$C{REST/headerIcon}}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/></cv> + <cv></a></cv> + <ck>footer</ck> = + <cv><a href='$U{$C{REST/footerLink}}'></cv> + <cv><img src='$U{$C{REST/footerIcon}}' style='float:right;padding-right:20px;height:32px'/></cv> + <cv></a></cv> +</p> + +<p> + Configuration files can also be accessed programmatically. + There are 3 primary ways of getting access to the config file: </p> <ul class='doctree'> <li class='jm'>{@link org.apache.juneau.microservice.Microservice#getConfig()} - <br>Any {@doc DefaultRestSvlVariables initialization-time variables} can be used. + <p>Any {@doc DefaultRestSvlVariables initialization-time variables} can be used.</p> <li class='jm'>{@link org.apache.juneau.rest.RestContext#getConfig()} - <br>Any {@doc DefaultRestSvlVariables initialization-time variables} can be used. + <p>Any {@doc DefaultRestSvlVariables initialization-time variables} can be used.</p> <h5 class='figure'>Example usage:</h5> <p class='bcode w800'> - <cc>#-------------------------------</cc> - <cc># Properties for MyHelloResource </cc> - <cc>#-------------------------------</cc> + <cc>#----------------------------------</cc> + <cc># Configuration for MyHelloResource </cc> + <cc>#----------------------------------</cc> <cs>[MyHelloResource]</cs> <ck>greeting</ck> = <cv>Hello world!</cv> </p> <p class='bcode w800'> + <cc>#---------------------------------</cc> + <cc># Contents of MyHelloResource.java </cc> + <cc>#---------------------------------</cc> <ja>@RestResource</ja>(...) <jk>public class</jk> MyHelloResource <jk>extends</jk> BasicRestServlet { - <jc>// Access config file when initializing fields.</jc> - <jk>private</jk> String greeting = getConfig().getString(<js>"MyHelloResource/greeting"</js>); + <jk>private</jk> String <jf>greeting</jf>; <jc>// Or access config file in servlet init method.</jc> <ja>@Override</ja> <jc>/* Servlet */</jc> <jk>public void</jk> init() { - String greeting = getConfig().getString(<js>"MyHelloResource/greeting"</js>); + Config c = getContext().getConfig(); + <jk>this</jk>.<jf>greeting</jf> = c.getString(<js>"MyHelloResource/greeting"</js>); } } </p> <p> - Additional user-defined variables can be defined at this level by adding a + Additional user-defined variables at the servlet level can be defined by adding a {@link org.apache.juneau.rest.annotation.HookEvent#INIT} hook method and using the {@link org.apache.juneau.rest.RestContextBuilder#vars(Class...)} method. </p> <li class='jm'> {@link org.apache.juneau.rest.RestRequest#getConfig()} - An instance method to access it from inside a REST method. - <br>Any {@doc DefaultRestSvlVariables initialization-time or request-time variables} can be used. + <p>Any {@doc DefaultRestSvlVariables initialization-time or request-time variables} can be used.</p> <h5 class='figure'>Example usage:</h5> <p class='bcode w800'> - <cc>#-----------------------------</cc> - <cc># Contents of microservice.cfg </cc> - <cc>#-----------------------------</cc> + <cc>#----------------------------------</cc> + <cc># Configuration for MyHelloResource</cc> + <cc>#----------------------------------</cc> <cs>[MyHelloResource]</cs> - <ck>greeting</ck> = <cv>Hello $RP{person}!</cv> - <ck>localizedGreeting</ck> = <cv>$L{HelloMessage,$RP{person}}</cv> + <ck>greeting</ck> = <cv>Hello $RP{person}!</cv> <cc>// $RP is RequestPathVar</cc> + <ck>localizedGreeting</ck> = <cv>$L{HelloMessage,$RP{person}}</cv> <cc>// $L is LocalizationVar with args</cc> </p> <p class='bcode w800'> <cc>#---------------------------------</cc> @@ -24584,109 +24824,107 @@ This particular example is needlessly complex, but it gives an idea of how variables can be used recursively to produce sophisticated results </p> -</div><!-- END: 12.3 - juneau-microservice-jetty.Config --> + +<h5 class='section'>See Also:</h5> +<ul class='doctree'> + <li class='link'>{@doc juneau-config} +</ul> +</div><!-- END: 12.5 - juneau-microservice-jetty.Config --> <!-- ==================================================================================================== --> -<h3 class='topic todo' onclick='toggle(this)'><a href='#juneau-microservice-jetty.ResourceClasses' id='juneau-microservice-jetty.ResourceClasses'>12.4 - Resource Classes</a></h3> -<div class='topic'><!-- START: 12.4 - juneau-microservice-jetty.ResourceClasses --> +<h3 class='topic new' onclick='toggle(this)'><a href='#juneau-microservice-jetty.JettyXml' id='juneau-microservice-jetty.JettyXml'>12.6 - Jetty.xml file</a></h3> +<div class='topic'><!-- START: 12.6 - juneau-microservice-jetty.JettyXml --> <p> - Now let's take a look at the resource classes themselves. - <br>The top-level page... -</p> -<p class='bpcode w800'> - http://localhost:10000 -</p> -<img class='bordered w800' src='doc-files/juneau-microservice-server.Running.1.png'> + The Jetty microservice comes with a bare-bones <code>jetty.xml</code> file which can be modified to suite any needs. +</p> <p> - ...is generated by this class... -<p class='bpcode w800'> - <ja>@RestResource</ja>( - path=<js>"/"</js>, - title=<js>"My Microservice"</js>, - description=<js>"Top-level resources page"</js>, - htmldoc=<ja>@HtmlDoc</ja>( - navlinks={ - <js>"options: servlet:/?method=OPTIONS"</js> - } - ), - children={ - HelloWorldResource.<jk>class</jk>, - ConfigResource.<jk>class</jk>, - LogsResource.<jk>class</jk> - } - ) - <jk>public class</jk> RootResources <jk>extends</jk> BasicRestServletJenaGroup { - <jc>// No code! </jc> - } + The <code>jetty.xml</code> can be located in either the <js>"."</js> or <js>"files"</js> working directory or classpath. + It can also be specified in any of the following ways: </p> <ul class='spaced-list'> <li> - The </l>title</l> and <l>description</l> annotations define the titles on the page. - <br>These can be globalized using <l>$L{...}</l> variables, or by defining specially-named properties in the - properties file for the resource. + Using the {@link org.apache.juneau.microservice.jetty.JettyMicroserviceBuilder#jettyXml(Object,boolean)} method to specify the location or contents + of the file. <li> - In this case, the <l>path</l> annotation defines the context root of your application since it was - not specified in the manifest or config file. - <br>Therefore, this resource is mapped to <l>http://localhost:10000</l>. + Specifying the location using a <code>Jetty-Config</code> value in the <code>MANIFEST.MF</code> file. + <p class='bcode w800'> + <mk>Jetty-Config:</mk> <mv>files/jetty.xml</mv> + </p> <li> - The <l>children</l> annotation make up the list of child resources. - <br>These child resources can be anything that extends from <l>Servlet</l>, although usually - they will be subclasses of {@link org.apache.juneau.rest.BasicRestServlet} or other resource groups. + Specifying the location using the <js>"Jetty/jettyXml"</js> configuration value. + <p class='bcode w800'> + <cc>#======================================================================================================================= + # Jetty settings + #=======================================================================================================================</cc> + <cs>[Jetty]</cs> + + <cc># Path of the jetty.xml file used to configure the Jetty server.</cc> + <ck>config</ck> = <cv>files/jetty.xml</cv> + </p> </ul> <p> - If you click the <l>helloWorld</l> link in your application, you'll get a simple hello world message: + SVL variables in the <code>jetty.xml</code> file are automatically resolved by the microservice. + This allows you to reference values in your configuration file from the <code>jetty.xml</code> file. </p> -<p class='bpcode w800'> - http://localhost:10000/helloWorld -</p> -<img class='bordered w800' src='doc-files/juneau-microservice-server.ResourceClasses.1.png'> <p> - ...which is generated by this class... + The HTTP port used is controlled via the following: </p> -<p class='bpcode w800'> - <ja>@RestResource</ja>( - path=<js>"/helloWorld"</js>, - title=<js>"Hello World example"</js>, - description=<js>"Simplest possible REST resource"</js> - ) - <jk>public class</jk> HelloWorldResource <jk>extends</jk> BasicRestServlet { +<ul class='spaced-list'> + <li> + The {@link org.apache.juneau.microservice.jetty.JettyMicroserviceBuilder#ports(int...)} method. + <p class='bcode w800'> + JettyMicroservice + .<jsm>create</jsm>() + .args(args) + .servlets(RootResource.<jk>class</jk>) + .port(1000,2000,0,0,0) <jc>// Try port 1000, then 2000, then 3 random ports.</jc> + .build() + .start() + </p> + <li> + The <js>"Jetty/ports"</js> configuration property. + <p class='bcode w800'> + <cc>#======================================================================================================================= + # Jetty settings + #=======================================================================================================================</cc> + <cs>[Jetty]</cs> - <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/*"</js>) - <jk>public</jk> String sayHello() { - <jk>return</jk> <js>"Hello world!"</js>; - } - } + <cc># Port to use for the jetty server. + # You can specify multiple ports. The first available will be used. '0' indicates to try a random port. + <ck>port</ck> = <cv>1000,2000,0,0,0</cv> + </p> +</ul> +<p> + The first available port is then made available through the system property <js>"availablePort"</js> so that it + can be referenced in our <code>jetty.xml</code> file. +</p> +<p class='bpcode w800'> + <xt><Set</xt> <xa>name</xa>=<xs>"connectors"</xs><xt>></xt> + <xt><Array</xt> <xa>type</xa>=<xs>"org.eclipse.jetty.server.Connector"</xs><xt>></xt> + <xt><Item></xt> + <xt><New</xt> <xa>class</xa>=<xs>"org.eclipse.jetty.server.ServerConnector"</xs><xt>></xt> + <xt><Arg></xt> + <xt><Ref</xt> <xa>refid</xa>=<xs>"ExampleServer"</xs> <xt>/></xt> + <xt></Arg></xt> + <xt><Set</xt> <xa>name</xa>=<xs>"port"</xs><xt>></xt>$S{availablePort,8080}<xt></Set></xt> + <xt></New></xt> + <xt></Item></xt> + <xt></Array></xt> + <xt></Set></xt> </p> -</div><!-- END: 12.4 - juneau-microservice-jetty.ResourceClasses --> - -<!-- ==================================================================================================== --> - -<h3 class='topic todo' onclick='toggle(this)'><a href='#juneau-microservice-jetty.PredefinedResourceClasses' id='juneau-microservice-jetty.PredefinedResourceClasses'>12.5 - Predefined Resource Classes</a></h3> -<div class='topic'><!-- START: 12.5 - juneau-microservice-jetty.PredefinedResourceClasses --> <p> - The following predefined resource classes are also provided for easy inclusion into your microservice: + The {@link org.apache.juneau.microservice.jetty.JettyMicroserviceBuilder#jettyServerFactory(JettyServerFactory)} method is also provided + to use your own customized Jetty server. </p> -<ul class='doctree'> - <li class='jc'>{@link org.apache.juneau.microservice.resources.ConfigResource} - - View and modify the external INI config file. - <li class='jc'>{@link org.apache.juneau.microservice.resources.DirectoryResource} - - View and modify file system directories. - <li class='jc'>{@link org.apache.juneau.microservice.resources.LogsResource} - - View and control generated log files. - <li class='jc'>{@link org.apache.juneau.microservice.resources.SampleRootResource} - - A sample root resource class to get started from. - <li class='jc'>{@link org.apache.juneau.microservice.resources.ShutdownResource} - - Shutdown and/or restart the JVM. -</ul> -</div><!-- END: 12.5 - juneau-microservice-jetty.PredefinedResourceClasses --> +</div><!-- END: 12.6 - juneau-microservice-jetty.JettyXml --> <!-- ==================================================================================================== --> -<h3 class='topic todo' onclick='toggle(this)'><a href='#juneau-microservice-jetty.UiCustomization' id='juneau-microservice-jetty.UiCustomization'>12.6 - UI Customization</a></h3> -<div class='topic'><!-- START: 12.6 - juneau-microservice-jetty.UiCustomization --> +<h3 class='topic new' onclick='toggle(this)'><a href='#juneau-microservice-jetty.UiCustomization' id='juneau-microservice-jetty.UiCustomization'>12.7 - UI Customization</a></h3> +<div class='topic'><!-- START: 12.7 - juneau-microservice-jetty.UiCustomization --> <p> - The Microservice project contains a <code>files/htdocs</code> working directly folder with predefined stylesheets and + The Microservice project contains a <code>files/htdocs</code> folder with predefined stylesheets and images. </p> <img style='width:200px' src='doc-files/juneau-microservice.UiCustomization.1.png'> @@ -24794,60 +25032,86 @@ <ck>RestContext.useClasspathResourceCaching.b</ck> = <cv>false</cv> </p> -</div><!-- END: 12.6 - juneau-microservice-jetty.UiCustomization --> +</div><!-- END: 12.7 - juneau-microservice-jetty.UiCustomization --> <!-- ==================================================================================================== --> -<h3 class='topic ' onclick='toggle(this)'><a href='#juneau-microservice-jetty.Extending' id='juneau-microservice-jetty.Extending'>12.7 - Extending RestMicroservice</a></h3> -<div class='topic'><!-- START: 12.7 - juneau-microservice-jetty.Extending --> +<h3 class='topic new' onclick='toggle(this)'><a href='#juneau-microservice-jetty.Extending' id='juneau-microservice-jetty.Extending'>12.8 - Extending JettyMicroservice</a></h3> +<div class='topic'><!-- START: 12.8 - juneau-microservice-jetty.Extending --> <p> - This example shows how the {@link org.apache.juneau.microservice.RestMicroservice} class + This example shows how the {@link org.apache.juneau.microservice.jetty.JettyMicroservice} class can be extended to implement lifecycle listener methods or override existing methods. - <br>We'll create a new class <l>com.foo.SampleCustomRestMicroservice</l>. -</p> -<p> - First, the manifest file needs to be modified to point to our new microservice: + <br>We'll create a new class <l>com.foo.MyJettyMicroservice</l>. </p> <p class='bpcode w800'> - <mk>Main-Class:</mk> com.foo.SampleCustomRestMicroservice + <jd>/** + * Sample subclass of a JettyMicroservice that provides customized behavior. + */</jd> + <jk>public class</jk> MyJettyMicroservice <jk>extends</jk> JettyMicroservice { + + <jk>public static void</jk> main(String[] args) <jk>throws</jk> Exception { + JettyMicroserviceBuilder builder = JettyMicroservice.<jsm>create</jsm>(); + <jk>new</jk> MyJettyMicroservice(builder).start().join(); + } + + <jk>public</jk> MyJettyMicroservice(JettyMicroserviceBuilder builder) <jk>throws</jk> Exception { + <jk>super</jk>(builder); + } + + <jc>// Customized code here.</jc> </p> <p> - Then we define the following class: + Optionally, you can extend the {@link org.apache.juneau.microservice.jetty.JettyMicroserviceBuilder} class as well: </p> <p class='bpcode w800'> - <jd>/** - * Sample subclass of a RestMicroservice that provides customized behavior. - * This class must be specified in the Main-Class entry in the manifest file and optionally - * a Main-ConfigFile entry. - */</jd> - <jk>public class</jk> SampleCustomRestMicroservice <jk>extends</jk> RestMicroservice { + <jk>public class</jk> MyJettyMicroserviceBuilder <jk>extends</jk> JettyMicroserviceBuilder { + <jk>int</jk> <jf>extraField</jf>; + <jd>/** - * Must implement a main method and call start()! + * Constructor (required). */</jd> - <jk>public static void</jk> main(String[] args) <jk>throws</jk> Exception { - <jk>new</jk> SampleCustomRestMicroservice(args).start().join(); - } + <jk>protected</jk> MyJettyMicroserviceBuilder() {} <jd>/** - * Must implement a constructor! - * - * <ja>@param</ja> args Command line arguments. - * <ja>@throws</ja> Exception + * Copy constructor (required). + * + * <ja>@param</ja> copyFrom The builder to copy settings from. */</jd> - <jk>public</jk> SampleCustomRestMicroservice(String[] args) <jk>throws</jk> Exception { - <jk>super</jk>(args); + <jk>protected</jk> MyJettyMicroserviceBuilder(MyJettyMicroserviceBuilder copyFrom) { + <jk>super</jk>(copyFrom); } + + <jc>// Additional setters</jc> + + <jk>public</jk> MyJettyMicroserviceBuilder extraField(<jk>int</jk> extraField) { + <jk>this</jk>.<jf>extraField</jf> = extraField; + <jk>return this</jk>; + } + + <jc>// Overridden methods</jc> + + <ja>@Override</ja> <jc>/* JettyMicroserviceBuilder */</jc> + <jk>public</jk> MyJettyMicroserviceBuilder copy() { + <jk>return new</jk> MyJettyMicroserviceBuilder(<jk>this</jk>); + } + + <ja>@Override</ja> <jc>/* JettyMicroserviceBuilder */</jc> + <jk>public</jk> MyJettyMicroserviceBuilder ports(<jk>int</jk>...ports) { + <jk>super</jk>.ports(ports); + <jk>return this</jk>; + } + + <ja>@Override</ja> <jc>/* JettyMicroserviceBuilder */</jc> + <jk>public</jk> MyJettyMicroserviceBuilder servlet(Class<? <jk>extends</jk> RestServlet> c) <jk>throws</jk> InstantiationException, IllegalAccessException { + <jk>super</jk>.servlet(c); + <jk>return this</jk>; + } + + ... + } </p> -<p> - The microservice APIs provide several useful methods that can be used or extended. -</p> -<h5 class='section'>See Also:</h5> -<ul class='doctree'> - <li class='jac'>{@link org.apache.juneau.microservice.Microservice} - <li class='jc'>{@link org.apache.juneau.microservice.RestMicroservice} -</ul> -</div><!-- END: 12.7 - juneau-microservice-jetty.Extending --> +</div><!-- END: 12.8 - juneau-microservice-jetty.Extending --> </div><!-- END: 12 - juneau-microservice-jetty --> <!-- ==================================================================================================== --> @@ -25769,6 +26033,11 @@ <li class='jc'>{@link org.apache.juneau.examples.core.rdf.RdfExample} - RdfXmlSerializer usage on serialize simple Pojo bean. <li class='jc'>{@link org.apache.juneau.examples.core.rdf.RdfComplexExample} - RdfXmlSerializer usage on serialize complex Pojo bean. </ul> + <li class='jp'><code>org.apache.juneau.examples.core.html</code> + <ul> + <li class='jc'>{@link org.apache.juneau.examples.core.html.HtmlSimpleExample} - HtmlSerializer usage on serialize simple Pojo bean. + <li class='jc'>{@link org.apache.juneau.examples.core.html.HtmlComplexExample} - HtmlSerializer usage on serialize complex Pojo bean. + </ul> </ul> </div><!-- END: 14.1 - juneau-examples-core.Examples --> </div><!-- END: 14 - juneau-examples-core --> diff --git a/juneau-doc/src/main/javadoc/resources/docs.txt b/juneau-doc/src/main/javadoc/resources/docs.txt index c219c17..ace5c1d 100644 --- a/juneau-doc/src/main/javadoc/resources/docs.txt +++ b/juneau-doc/src/main/javadoc/resources/docs.txt @@ -231,7 +231,8 @@ juneau-microservice-jetty-template.RestMicroservice = #juneau-microservice-jetty juneau-microservice-jetty-template.RestMicroservice.Extending = #juneau-microservice-jetty-template.RestMicroservice.Extending, Overview > juneau-microservice-jetty-template > RestMicroservice > Extending RestMicroservice juneau-microservice-jetty-template.UiCustomization = #juneau-microservice-jetty-template.UiCustomization, Overview > juneau-microservice-jetty-template > UI Customization juneau-microservice-jetty.Config = #juneau-microservice-jetty.Config, Overview > juneau-microservice-jetty > Config -juneau-microservice-jetty.Extending = #juneau-microservice-jetty.Extending, Overview > juneau-microservice-jetty > Extending RestMicroservice +juneau-microservice-jetty.Extending = #juneau-microservice-jetty.Extending, Overview > juneau-microservice-jetty > Extending JettyMicroservice +juneau-microservice-jetty.JettyXml = #juneau-microservice-jetty.JettyXml, Overview > juneau-microservice-jetty > Jetty.xml file juneau-microservice-jetty.LifecycleMethods = #juneau-microservice-jetty.LifecycleMethods, Overview > juneau-microservice-jetty > Lifecycle Methods juneau-microservice-jetty.Overview = #juneau-microservice-jetty.Overview, Overview > juneau-microservice-jetty > Overview juneau-microservice-jetty.PredefinedResourceClasses = #juneau-microservice-jetty.PredefinedResourceClasses, Overview > juneau-microservice-jetty > Predefined Resource Classes diff --git a/juneau-doc/src/main/javadoc/resources/fragments/toc.html b/juneau-doc/src/main/javadoc/resources/fragments/toc.html index a76bd18..7ecbb7a 100644 --- a/juneau-doc/src/main/javadoc/resources/fragments/toc.html +++ b/juneau-doc/src/main/javadoc/resources/fragments/toc.html @@ -353,11 +353,12 @@ <ol> <li><p class='new'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.Overview'>Overview</a></p> <li><p class='new'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.LifecycleMethods'>Lifecycle Methods</a></p> - <li><p class='todo'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.Config'>Config</a></p> - <li><p class='todo'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.ResourceClasses'>Resource Classes</a></p> - <li><p class='todo'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.PredefinedResourceClasses'>Predefined Resource Classes</a></p> - <li><p class='todo'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.UiCustomization'>UI Customization</a></p> - <li><p class=''><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.Extending'>Extending RestMicroservice</a></p> + <li><p class='new'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.ResourceClasses'>Resource Classes</a></p> + <li><p class='new'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.PredefinedResourceClasses'>Predefined Resource Classes</a></p> + <li><p class='new'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.Config'>Config</a></p> + <li><p class='new'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.JettyXml'>Jetty.xml file</a></p> + <li><p class='new'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.UiCustomization'>UI Customization</a></p> + <li><p class='new'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty.Extending'>Extending JettyMicroservice</a></p> </ol> <li><p class='toc2 todo'><a class='doclink' href='{OVERVIEW_URL}#juneau-microservice-jetty-template'>juneau-microservice-jetty-template</a></p> <ol>