http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/e87529b2/content/components.html ---------------------------------------------------------------------- diff --git a/content/components.html b/content/components.html new file mode 100644 index 0000000..e1681ee --- /dev/null +++ b/content/components.html @@ -0,0 +1,227 @@ +<!DOCTYPE html> +<html> +<head> +<style> + @import url("styles/juneau-code.css"); + @import url("styles/juneau-doc.css"); +</style> +</head> +<body> + <!-- =========================================================================================================== --> + <!-- === COMPONENTS ============================================================================================ --> + <!-- =========================================================================================================== --> + + <h5 class='toc'>Components</h5> + <div> + <p> + We've strived to keep prerequisites to an absolute minimum in order to make adoption as easy as possible. + </p> + <p> + The library consists of the following artifacts found in the Maven group <code>"org.apache.juneau"</code>: + </p> + <table class='styled' style='min-width:800px;'> + <tr> + <th>Category</th><th>Maven Artifacts</th><th>Description</th><th>Prereqs</th> + </tr> + <tr class='dark bb'> + <td rowspan="5" style='text-align:center;font-weight:bold;padding:20px;' class='code'>juneau-core</td> + <td class='code'>juneau-marshall</td> + <td>Serializers and parsers for: + <ul style='margin:0px 10px;'> + <li>JSON + <li>XML + <li>HTML + <li>UON + <li>URL-Encoding + <li>MessagePack + <li>SOAP/XML + <li>CSV + <li>BSON (coming soon) + <li>YAML (coming soon) + <li>Protobuf (coming soon) + </ul> + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 6 + </ul> + </td> + </tr> + <tr class='dark bb'> + <td class='code'>juneau-marshall-rdf</td> + <td> + Serializers and parsers for: + <ul style='margin:0px 10px;'> + <li>RDF/XML + <li>RDF/XML-Abbrev + <li>N-Triple + <li>Turtle + <li>N3 + </ul> + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 6 + <li>Apache Jena 2.7.1 + </ul> + </td> + </tr> + <tr class='dark bb'> + <td class='code'>juneau-dto</td> + <td> + Data Transfer Objects for: + <ul style='margin:0px 10px;'> + <li>HTML5 + <li>Atom + <li>Cognos + <li>JSON-Schema + <li>Swagger 2.0 + </ul> + </td> + <td><ul style='margin:0px 10px;'><li>Java 6</li></ul></td> + </tr> + <tr class='dark bb'> + <td class='code'>juneau-svl</td> + <td> + Simple Variable Language API + </td> + <td><ul style='margin:0px 10px;'><li>Java 6</li></ul></td> + </tr> + <tr class='dark bb'> + <td class='code'>juneau-config</td> + <td> + Configuration file API + </td> + <td><ul style='margin:0px 10px;'><li>Java 6</li></ul></td> + </tr> + <tr class='light bb'> + <td rowspan="3" style='text-align:center;font-weight:bold;padding:20px;' class='code'>juneau-rest</td> + <td class='code'>juneau-rest-server</td> + <td> + REST Servlet API + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 6 + <li>Servlet 3.1 + </ul> + </td> + </tr> + <tr class='light bb'> + <td class='code'>juneau-rest-server-jaxrs</td> + <td> + Optional JAX-RS support + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 6 + <li>JAX-RS 2.0 + </ul> + </td> + </tr> + <tr class='light bb'> + <td class='code'>juneau-rest-client</td> + <td> + REST Client API + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 6 + <li>Apache HttpClient 4.5.3 + </ul> + </td> + </tr> + <tr class='dark bb'> + <td rowspan="2" style='text-align:center;font-weight:bold;padding:20px;' class='code'>juneau-microservice</td> + <td class='code'>juneau-microservice-server</td> + <td> + REST Microservice Server API + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 8 + <li>Eclipse Jetty 9.4.3 + </ul> + </td> + </tr> + <tr class='dark bb'> + <td class='code'>juneau-microservice-template</td> + <td> + Developer template project + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 8 + <li>Eclipse Jetty 9.4.3 + </ul> + </td> + </tr> + <tr class='light bb'> + <td rowspan="2" style='text-align:center;font-weight:bold;padding:20px;' class='code'>juneau-examples</td> + <td class='code'>juneau-examples-core</td> + <td> + Core code examples + </td> + <td></td> + </tr> + <tr class='light bb'> + <td class='code'>juneau-example-rest</td> + <td> + REST code examples + </td> + <td></td> + </tr> + <tr class='dark bb'> + <td rowspan="1" style='text-align:center;font-weight:bold;padding:20px;' class='code'>juneau-all</td> + <td class='code'><code>juneau-all</code></td> + <td> + Combination of the following: + <ul style='margin:0px 10px;'> + <li>juneau-marshall + <li>juneau-dto + <li>juneau-svl + <li>juneau-config + <li>juneau-rest-server + <li>juneau-rest-client + </ul> + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 6 + <li>Servlet 3.1 + <li>Apache HttpClient 4.5.3 + </ul> + </td> + </tr> + </table> + + <p> + The current version of Juneau is <code>6.4.0-incubating</code>. + The easiest way to pull in the library is through the following maven dependency: + </p> + <p class='bcode' style='width:500px;'> + <xt><dependency></xt> + <xt><groupId></xt>org.apache.juneau<xt></groupId></xt> + <xt><artifactId></xt>juneau-all<xt></artifactId></xt> + <xt><version></xt>6.4.0-incubating<xt></version></xt> + <xt></dependency></xt> + </p> + <p> + If you would like to work with the bleeding-edge code, you can access the <code>6.4.1-incubating-SNAPSHOT</code> + version through the following repository: + </p> + <p class='bcode' style='width:500px;'> + <xt><pluginRepositories> + <pluginRepository> + <id><xv>apache.snapshots</xv></id> + <url><xv>http://repository.apache.org/snapshots/</xv></url> + <snapshots> + <enabled><xv>true</xv></enabled> + <updatePolicy><xv>always</xv></updatePolicy> + </snapshots> + </pluginRepository> + </pluginRepositories></xt> + </p> + </div> +</body> +</html> \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/e87529b2/content/config.html ---------------------------------------------------------------------- diff --git a/content/config.html b/content/config.html new file mode 100644 index 0000000..c72943b --- /dev/null +++ b/content/config.html @@ -0,0 +1,140 @@ +<!DOCTYPE html> +<html> +<head> +<style> + @import url("styles/juneau-code.css"); + @import url("styles/juneau-doc.css"); +</style> +</head> +<body> + <!-- ======================================================================================================= --> + <!-- === JUNEAU-CONFIG ===================================================================================== --> + <!-- ======================================================================================================= --> + + <h5 class='toc' id='juneau-config'>juneau-config</h5> + <div> + <h6 class='figure'>Maven Dependency</h6> + <p class='bcode' style='width:500px;'> + <xt><dependency></xt> + <xt><groupId></xt>org.apache.juneau<xt></groupId></xt> + <xt><artifactId></xt>juneau-config<xt></artifactId></xt> + <xt><version></xt>6.4.0-incubating<xt></version></xt> + <xt></dependency></xt> + </p> + + <h6 class='figure'>Java Library</h6> + <p class='bcode' style='width:500px;'> + juneau-config-6.4.0-incubating.jar + </p> + + <h6 class='figure'>OSGi Module</h6> + <p class='bcode' style='width:500px;'> + org.apache.juneau.config_6.4.0-incubating.jar + </p> + + <p> + The <code>juneau-config</code> module defines an API allows you to interact with INI files using POJOs. + It builds upon the marshalling and SVL APIs to provide sophisticated dynamic configuration files. + <p> + <p class='bcode'> + <cc>#--------------------------</cc> + <cc># My section</cc> + <cc>#--------------------------</cc> + <cs>[MySection]</cs> + + <cc># An integer</cc> + <ck>anInt</ck> = <cv>1</cv> + + <cc># A boolean</cc> + <ck>aBoolean</ck> = <cv>true</cv> + + <cc># An int array</cc> + <ck>anIntArray</ck> = <cv>[1,2,3]</cv> + + <cc># A POJO that can be converted from a String</cc> + <ck>aURL</ck> = <cv>http://foo </cv> + + <cc># A POJO that can be converted from JSON</cc> + <ck>aBean</ck> = <cv>{foo:'bar',baz:123}</cv> + + <cc># A system property</cc> + <ck>locale</ck> = <cv>$S{java.locale, en_US}</cv> + + <cc># An environment variable</cc> + <ck>path</ck> = <cv>$E{PATH, unknown}</cv> + + <cc># A manifest file entry</cc> + <ck>mainClass</ck> = <cv>$MF{Main-Class}</cv> + + <cc># Another value in this config file</cc> + <ck>sameAsAnInt</ck> = <cv>$C{MySection/anInt}</cv> + + <cc># A command-line argument in the form "myarg=foo"</cc> + <ck>myArg</ck> = <cv>$ARG{myarg}</cv> + + <cc># The first command-line argument</cc> + <ck>firstArg</ck> = <cv>$ARG{0}</cv> + + <cc># Look for system property, or env var if that doesn't exist, or command-line arg if that doesn't exist.</cc> + <ck>nested</ck> = <cv>$S{mySystemProperty,$E{MY_ENV_VAR,$ARG{0}}}</cv> + + <cc># A POJO with embedded variables</cc> + <ck>aBean2</ck> = <cv>{foo:'$ARG{0}',baz:$C{MySection/anInt}}</cv> + </p> + <p> + You're probably wondering "why INI files?" + The beauty of these INI files is that they're easy to read and modify, yet sophisticated enough to allow you to + store arbitrary-complex data structures and retrieve them as simple values or complex POJOs: + </p> + <p class='bcode'> + <jc>// Load our config file</jc> + ConfigFile f = <jk>new</jk> ConfigFileBuilder().build(<js>"MyIniFile.cfg"</js>); + + <jk>int</jk> anInt = cf.getInt(<js>"MySection/anInt"</js>); + <jk>boolean</jk> aBoolean = cf.getBoolean(<js>"MySection/aBoolean"</js>); + <jk>int</jk>[] anIntArray = cf.getObject(<jk>int</jk>[].<jk>class</jk>, <js>"MySection/anIntArray"</js>); + URL aURL = cf.getObject(URL.<jk>class</jk>, <js>"MySection/aURL"</js>); + MyBean aBean = cf.getObject(MyBean.<jk>class</jk>, <js>"MySection/aBean"</js>); + Locale locale = cf.getObject(Locale.<jk>class</jk>, <js>"MySection/locale"</js>); + String path = cf.getString(<js>"MySection/path"</js>); + String mainClass = cf.getString(<js>"MySection/mainClass"</js>); + <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> + <p> + By default, values are LAX JSON (i.e. unquoted attributes, single quotes) except for top-level strings which are left unquoted. + Any parsable object types are supported as values (e.g. arrays, collections, beans, swappable objects, enums, etc...). + </p> + <p> + One of the more powerful aspects of the REST servlets is that you can pull values directly from + config files by using the <js>"$C"</js> variable in annotations. + <br>For example, the HTML stylesheet for your REST servlet can be defined in a config file like so: + </p> + <p class='bcode'> + <ja>@RestResource</ja>( + path=<js>"/myResource"</js>, + config=<js>"$S{my.config.file}"</js>, <jc>// Path to config file (here pulled from a system property)</jc> + stylesheet=<js>"$C{MyResourceSettings/myStylesheet}"</js> <jc>// Stylesheet location pulled from config file.</jc> + ) + <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { + </p> + <p> + Other features: + </p> + <ul class='spaced-list'> + <li>A listener API that allows you to, for example, reinitialize your REST resource if the config file + changes, or listen for changes to particular sections or values. + <li>Config files can be modified through the ConfigFile class (e.g. add/remove/modify sections and keys, add/remove comments and whitespace, etc...). + <br>When using these APIs, you <b>DO NOT</b> lose formatting in your existing configuration file. + All existing whitespace and comments are preserved for you! + <li>Config file sections can be used to directly populate beans. + <li>Config file sections can be accessed and manipulated through Java interface proxies. + </ul> + + <ul class='doctree'> + <li class='link'>See <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-config'>juneau-config</a> for more information. + </ul> + </div> +</body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/e87529b2/content/doap.rdf ---------------------------------------------------------------------- diff --git a/content/doap.rdf b/content/doap.rdf index 221ee8f..dbd7546 100644 --- a/content/doap.rdf +++ b/content/doap.rdf @@ -54,7 +54,6 @@ under the License. <Version> <name>6.4.0</name> <created>2017-10-05</created> - <revision>0.16.0</revision> </Version> </release> <repository> http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/e87529b2/content/dto.html ---------------------------------------------------------------------- diff --git a/content/dto.html b/content/dto.html new file mode 100644 index 0000000..c257a1b --- /dev/null +++ b/content/dto.html @@ -0,0 +1,255 @@ +<!DOCTYPE html> +<html> +<head> +<style> + @import url("styles/juneau-code.css"); + @import url("styles/juneau-doc.css"); +</style> +</head> +<body> + <!-- ======================================================================================================= --> + <!-- === JUNEAU-DTO ======================================================================================== --> + <!-- ======================================================================================================= --> + + <h5 class='toc' id='juneau-dto'>juneau-dto</h5> + <div> + <h6 class='figure'>Maven Dependency</h6> + <p class='bcode' style='width:500px;'> + <xt><dependency></xt> + <xt><groupId></xt>org.apache.juneau<xt></groupId></xt> + <xt><artifactId></xt>juneau-dto<xt></artifactId></xt> + <xt><version></xt>6.4.0-incubating<xt></version></xt> + <xt></dependency></xt> + </p> + + <h6 class='figure'>Java Library</h6> + <p class='bcode' style='width:500px;'> + juneau-dto-6.4.0-incubating.jar + </p> + + <h6 class='figure'>OSGi Module</h6> + <p class='bcode' style='width:500px;'> + org.apache.juneau.dto_6.4.0-incubating.jar + </p> + + <p> + Data Transfer Object libraries are provided for a variety of languages that allow you to serialize commonly-used + documents. + </p> + <ul> + <li>HTML5 + <li>Atom + <li>Cognos + <li>JSON-Schema + <li>Swagger 2.0 + </ul> + <p> + HTML5 documents and fragments can be constructed using the HTML5 DTOs and HTML or XML serializers: + </p> + <p class='bcode'> + <jk>import static</jk> org.apache.juneau.dto.html5.HtmlBuilder.*; + + Object myform = + <jsm>form</jsm>().action(<js>"/submit"</js>).method(<js>"POST"</js>) + .children( + <js>"Position (1-10000): "</js>, <jsm>input</jsm>(<js>"number"</js>).name(<js>"pos"</js>).value(1), <jsm>br</jsm>(), + <js>"Limit (1-10000): "</js>, <jsm>input</jsm>(<js>"number"</js>).name(<js>"limit"</js>).value(100), <jsm>br</jsm>(), + <jsm>button</jsm>(<js>"submit"</js>, <js>"Submit"</js>), + <jsm>button</jsm>(<js>"reset"</js>, <js>"Reset"</js>) + ); + + String html = HtmlSerializer.<jsf>DEFAULT</jsf>.serialize(myform); + </p> + <p class='bcode'><xt> + <form <xa>action</xa>=<xs>'/submit'</xs> <xa>method</xa>=<xs>'POST'</xs>> + <xv>Position (1-10000):</xv> <input <xa>name</xa>=<xs>'pos'</xs> <xa>type</xa>=<xs>'number'</xs> <xa>value</xa>=<xs>'1'</xs>/><br/> + <xv>Limit (1-10000):</xv> <input <xa>name</xa>=<xs>'pos'</xs> <xa>type</xa>=<xs>'number'</xs> <xa>value</xa>=<xs>'100'</xs>/><br/> + <button <xa>type</xa>=<xs>'submit'</xs>><xv>Submit</xv></button> + <button <xa>type</xa>=<xs>'reset'</xs>><xv>Reset</xv></button> + </form> + </xt></p> + <p> + And you're not limited to just HTML. The HTML5 beans are POJOs that can be serialized using any + of the serializers, such as lax JSON: + </p> + <p class='bcode'> + { + <jf>_type</jf>: <js>'form'</js>, + <jf>a</jf>: { <jf>action</jf>: <js>'/submit'</js>, <jf>method</jf>: <js>'POST'</js> }, + <jf>c</jf>: [ + <js>'Position (1-10000): '</js>, + { <jf>_type</jf>: <js>'input'</js>, <jf>a</jf>: { <jf>type</jf>: <js>'number'</js>, <jf>name</jf>: <js>'pos'</js>, <jf>value</jf>: 1 } }, + { <jf>_type</jf>: <js>'br'</js> }, + <js>'Limit (1-10000): '</js>, + { <jf>_type</jf>: <js>'input'</js>, <jf>a</jf>: { <jf>type</jf>: <js>'number'</js>, <jf>name</jf>: <js>'limit'</js>, <jf>value</jf>: 100 } }, + { <jf>_type</jf>: <js>'br'</js> }, + { <jf>_type</jf>: <js>'button'</js>, <jf>a</jf>: { <jf>type</jf>: <js>'submit'</js> }, <jf>c</jf>: [ <js>'Submit'</js> ] }, + { <jf>_type</jf>: <js>'button'</js>, <jf>a</jf>: { <jf>type</jf>: <js>'reset'</js> }, <jf>c</jf>: [ <js>'Reset'</js> ] } + ] + } + </p> + + <p> + ATOM feeds can be constructed using the ATOM DTOs and XML serializer: + </p> + <p class='bcode'> + <jk>import static</jk> org.apache.juneau.dto.atom.AtomBuilder.*; + + Feed feed = + <jsm>feed</jsm>(<js>"tag:juneau.apache.org"</js>, <js>"Juneau ATOM specification"</js>, <js>"2016-01-02T03:04:05Z"</js>) + .subtitle(<jsm>text</jsm>(<js>"html"</js>).text(<js>"Describes <em>stuff</em> about Juneau"</js>)) + .links( + <jsm>link</jsm>(<js>"alternate"</js>, <js>"text/html"</js>, <js>"http://juneau.apache.org/";</js>).hreflang(<js>"en"</js>), + <jsm>link</jsm>(<js>"self"</js>, <js>"application/atom+xml"</js>, <js>"http://juneau.apache.org/feed.atom";</js>) + ) + .rights(<js>"Copyright (c) 2016, Apache Foundation"</js>) + .entries( + <jsm>entry</jsm>(<js>"tag:juneau.sample.com,2013:1.2345"</js>, <js>"Juneau ATOM specification snapshot"</js>, <js>"2016-01-02T03:04:05Z"</js>) + .published(<js>"2016-01-02T03:04:05Z"</js>) + .content( + <jsm>content</jsm>(<js>"xhtml"</js>) + .lang(<js>"en"</js>) + .base(<js>"http://www.apache.org/";</js>) + .text(<js>"<div><p><i>[Update: Juneau supports ATOM.]</i></p></div>"</js>) + ) + ); + + <jc>// Serialize to ATOM/XML</jc> + String atomXml = XmlSerializer.<jsf>DEFAULT</jsf>.serialize(feed); + </p> + <p class='bcode'> + <xt><feed></xt> + <xt><id></xt> + tag:juneau.apache.org + <xt></id></xt> + <xt><link</xt> <xa>href</xa>=<xs>'http://juneau.apache.org/'</xs> <xa>rel</xa>=<xs>'alternate'</xs> <xa>type</xa>=<xs>'text/html'</xs> <xa>hreflang</xa>=<xs>'en'</xs>/<xt>></xt> + <xt><link</xt> <xa>href</xa>=<xs>'http://juneau.apache.org/feed.atom'</xs> <xa>rel</xa>=<xs>'self'</xs> <xa>type</xa>=<xs>'application/atom+xml'</xs>/<xt>></xt> + <xt><rights></xt> + Copyright (c) 2016, Apache Foundation + <xt></rights></xt> + <xt><title</xt> <xa>type</xa>=<xs>'text'</xs>></xt> + Juneau ATOM specification + <xt></title></xt> + <xt><updated></xt>2016-01-02T03:04:05Z<xt></updated></xt> + <xt><subtitle</xt> <xa>type</xa>=<xs>'html'</xs><xt>></xt> + Describes <em>stuff</em> about Juneau + <xt></subtitle></xt> + <xt><entry></xt> + <xt><id></xt> + tag:juneau.apache.org + <xt></id></xt> + <xt><title></xt> + Juneau ATOM specification snapshot + <xt></title></xt> + <xt><updated></xt>2016-01-02T03:04:05Z<xt></updated></xt> + <xt><content</xt> <xa>base</xa>=<xs>'http://www.apache.org/'</xs> <xa>lang</xa>=<xs>'en'</xs> <xa>type</xa>=<xs>'xhtml'</xs><xt>></xt> + <xt><div</xt> <xa>xmlns</xa>=<xs>"http://www.w3.org/1999/xhtml";</xs><xt>><p><i></xt>[Update: Juneau supports ATOM.]<xt></i></p></div></xt> + <xt></content></xt> + <xt><published></xt>2016-01-02T03:04:05Z<xt></published></xt> + <xt></entry></xt> + <xt></feed></xt> + </p> + <p> + Swagger documents can be constructed using the Swagger DTOs and JSON serializer: + </p> + <p class='bcode'> + <jk>import static</jk> org.apache.juneau.dto.swagger.SwaggerBuilder.*; + + Swagger swagger = <jsm>swagger</jsm>() + .swagger(<js>"2.0"</js>) + .info( + <jsm>info</jsm>(<js>"Swagger Petstore"</js>, <js>"1.0.0"</js>) + .description(<js>"This is a sample server Petstore server."</js>) + .termsOfService(<js>"http://swagger.io/terms/";</js>) + .contact( + <jsm>contact</jsm>().email(<js>"[email protected]"</js>) + ) + .license( + <jsm>license</jsm>(<js>"Apache 2.0"</js>).url(<js>"http://www.apache.org/licenses/LICENSE-2.0.html";</js>) + ) + ) + .path(<js>"/pet"</js>, <js>"post"</js>, + <jsm>operation</jsm>() + .tags(<js>"pet"</js>) + .summary(<js>"Add a new pet to the store"</js>) + .description(<js>""</js>) + .operationId(<js>"addPet"</js>) + .consumes(MediaType.<jsf>JSON</jsf>, MediaType.<jsf>XML</jsf>) + .produces(MediaType.<jsf>JSON</jsf>, MediaType.<jsf>XML</jsf>) + .parameters( + <jsm>parameterInfo</jsm>(<js>"body"</js>, <js>"body"</js>) + .description(<js>"Pet object that needs to be added to the store"</js>) + .required(<jk>true</jk>) + ) + .response(405, <jsm>responseInfo</jsm>(<js>"Invalid input"</js>)) + ); + + <jc>// Serialize to Swagger/JSON</jc> + String swaggerJson = JsonSerializer.<jsf>DEFAULT_READABLE</jsf>.serialize(swagger); + </p> + <p class='bcode'> + { + <jf>"swagger"</jf>: <js>"2.0"</js>, + <jf>"info"</jf>: { + <jf>"title"</jf>: <js>"Swagger Petstore"</js>, + <jf>"description"</jf>: <js>"This is a sample server Petstore server."</js>, + <jf>"version"</jf>: <js>"1.0.0"</js>, + <jf>"termsOfService"</jf>: <js>"http://swagger.io/terms/";</js>, + <jf>"contact"</jf>: { + <jf>"email"</jf>: <js>"[email protected]"</js> + }, + <jf>"license"</jf>: { + <jf>"name"</jf>: <js>"Apache 2.0"</js>, + <jf>"url"</jf>: <js>"http://www.apache.org/licenses/LICENSE-2.0.html";</js> + } + }, + <jf>"paths"</jf>: { + <jf>"/pet"</jf>: { + <jf>"post"</jf>: { + <jf>"tags"</jf>: [ + <js>"pet"</js> + ], + <jf>"summary"</jf>: <js>"Add a new pet to the store"</js>, + <jf>"description"</jf>: <js>""</js>, + <jf>"operationId"</jf>: <js>"addPet"</js>, + <jf>"consumes"</jf>: [ + <js>"application/json"</js>, + <js>"text/xml"</js> + ], + <jf>"produces"</jf>: [ + <js>"application/json"</js>, + <js>"text/xml"</js> + ], + <jf>"parameters"</jf>: [ + { + <jf>"in"</jf>: <js>"body"</js>, + <jf>"name"</jf>: <js>"body"</js>, + <jf>"description"</jf>: <js>"Pet object that needs to be added to the store"</js>, + <jf>"required"</jf>: <jk>true</jk> + } + ], + <jf>"responses"</jf>: { + <jf>"405"</jf>: { + <jf>"description"</jf>: <js>"Invalid input"</js> + } + } + } + } + }, + } + </p> + <p> + Note that these DTOs can also be serialized to any of the other supported languages such as JSON or MessagePack! + And they can be parsed back into their original objects! + </p> + <p> + As a convenience, you can also simply call <code>toString()</code> on any of these DTOs and they will + be serialized directly to a string in the typical language (e.g. HTML5 beans to HTML, Swagger to JSON, etc...). + </p> + + <ul class='doctree'> + <li class='link'>See <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-dto'>juneau-dto</a> for more information. + </ul> + </div> +</body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/e87529b2/content/examples.html ---------------------------------------------------------------------- diff --git a/content/examples.html b/content/examples.html new file mode 100644 index 0000000..cb60c1a --- /dev/null +++ b/content/examples.html @@ -0,0 +1,90 @@ +<!DOCTYPE html> +<html> +<head> +<style> + @import url("styles/juneau-code.css"); + @import url("styles/juneau-doc.css"); +</style> +</head> +<body> + <!-- =========================================================================================================== --> + <!-- === JUNEAU-EXAMPLES ======================================================================================= --> + <!-- =========================================================================================================== --> + + <h5 class='toc' id='juneau-examples'>juneau-examples</h5> + <div> + + <!-- ======================================================================================================= --> + <!-- === JUNEAU-EXAMPLES-CORE ============================================================================== --> + <!-- ======================================================================================================= --> + + <h6 class='toc' id='juneau-examples-core'>juneau-examples-core</h6> + <div> + + <h6 class='figure'>Archive File</h6> + <p class='bcode' style='width:500px;'> + juneau-examples-core-6.4.0-incubating.zip + </p> + + <p> + The <code>juneau-examples-core</code> project contains various code examples for using the core APIs. + </p> + <p> + The project project can be loaded into your workspace by importing the + <code>juneau-examples-core-6.4.0-incubating.zip</code> file. + </p> + <p> + Once loaded, you should see the following project structure: + </p> + <img class='bordered' src='images/juneau-examples-core.import3.png' style='width:459px'> + + <p> + FYI...<br> + The Core library samples are currently a work-in-progress so there's not much here yet. + </p> + + + <ul class='doctree'> + <li class='link'>See <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-examples-core'>juneau-examples-core</a> for more information. + </ul> + </div> + + <!-- ======================================================================================================= --> + <!-- === JUNEAU-EXAMPLES-REST ============================================================================== --> + <!-- ======================================================================================================= --> + + <h6 class='toc' id='juneau-examples-rest'>juneau-examples-rest</h6> + <div> + + <h6 class='figure'>Archive File</h6> + <p class='bcode' style='width:500px;'> + juneau-examples-rest-6.4.0-incubating.zip + </p> + + <p> + The <code>juneau-examples-core</code> project provides various code examples on how to use the core + libraries. + </p> + <p> + The project project can be loaded into your workspace by importing the + <code>juneau-examples-rest-6.4.0-incubating.zip</code> file. + </p> + <p> + Once loaded, you should see the following project structure: + </p> + <img class='bordered' src='images/juneau-examples-rest.import3.png' style='width:412px'> + <p> + The microservice can be started from the <code>juneau-examples-rest.launch</code> file. + It will start up the microservice on port 10000 which you can then view through a browser: + </p> + <img class='bordered' src='images/juneau-examples-rest.import4.png' style='width:466px'> + + <ul class='doctree'> + <li class='link'>See <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-examples-rest'>juneau-examples-rest</a> for more information. + </ul> + </div> + + </div> + +</body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/e87529b2/content/index.html ---------------------------------------------------------------------- diff --git a/content/index.html b/content/index.html index 714e030..c3d9a03 100644 --- a/content/index.html +++ b/content/index.html @@ -41,7 +41,7 @@ } nav { float: left; - width: 160px; + width: 150px; margin: 40px 20px; padding: 1em; border: 1px solid gray; @@ -54,6 +54,8 @@ } nav ul { list-style-type: none; padding: 0; } nav ul li { padding: 5px 0px; } + nav ul ul { padding: 0px 10px; } + nav ul ul li { padding: 5px 0px 0px 3px; font-size: smaller; } nav ul a { text-decoration: none; color: rgb(44, 69, 87); } nav ul a:hover { font-weight: normal; } nav ul a.selected { font-weight: normal; } @@ -145,14 +147,26 @@ <nav> <ul> - <li><a href='about.html' id='about' onclick="return select(this)">About</a></li> + <li><a href='about.html' id='about' onclick="return select(this)">About</a> + <li><a href='components.html' id='components' onclick="return select(this)">Components</a> + <ul> + <li><a href='marshall.html' id='marshall' onclick="return select(this)">marshall</a> + <li><a href='dto.html' id='dto' onclick="return select(this)">dto</a> + <li><a href='svl.html' id='svl' onclick="return select(this)">svl</a> + <li><a href='config.html' id='config' onclick="return select(this)">config</a> + <li><a href='rest-server.html' id='rest-server' onclick="return select(this)">rest-server</a> + <li><a href='rest-client.html' id='rest-client' onclick="return select(this)">rest-client</a> + <li><a href='microservice.html' id='microservice' onclick="return select(this)">microservice</a> + <li><a href='examples.html' id='examples' onclick="return select(this)">examples</a> + </ul> + </li> <li><a href='documentation.html' id='documentation' onclick="return select(this)">Documentation</a></li> <li><a href='downloads.html' id='downloads' onclick="return select(this)">Downloads</a></li> <li><a href='sourceCode.html' id='sourceCode' onclick="return select(this)">Source Code</a></li> <li><a href='issues.html' id='issues' onclick="return select(this)">Issues</a></li> <li><a href='community.html' id='community' onclick="return select(this)">Community</a></li> <li><a href='twitter.html' id='twitter' onclick="return select(this)">Twitter</a></li> - <li><a href="http://www.apache.org/licenses/LICENSE-2.0"; target="_blank">License</a></li> + <li><a href="http://www.apache.org/licenses/"; target="_blank">License</a></li> <li><a href="http://www.apache.org/security"; target="_blank">Security</a></li> <li><a href="http://www.apache.org/foundation/sponsorship.html"; target="_blank">Donate</a></li> <li><a href="http://www.apache.org/foundation/thanks.html"; target="_blank">Thanks</a></li> http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/e87529b2/content/marshall.html ---------------------------------------------------------------------- diff --git a/content/marshall.html b/content/marshall.html new file mode 100644 index 0000000..5daa3a7 --- /dev/null +++ b/content/marshall.html @@ -0,0 +1,417 @@ +<!DOCTYPE html> +<html> +<head> +<style> + @import url("styles/juneau-code.css"); + @import url("styles/juneau-doc.css"); +</style> +</head> +<body> + <!-- ======================================================================================================= --> + <!-- === JUNEAU-MARSHALL =================================================================================== --> + <!-- ======================================================================================================= --> + + <h5 class='toc' id='juneau-marshall'>juneau-marshall</h5> + <div> + <h6 class='figure'>Maven Dependency</h6> + <p class='bcode' style='width:500px;'> + <xt><dependency></xt> + <xt><groupId></xt>org.apache.juneau<xt></groupId></xt> + <xt><artifactId></xt>juneau-marshall<xt></artifactId></xt> + <xt><version></xt>6.4.0-incubating<xt></version></xt> + <xt></dependency></xt> + </p> + + <h6 class='figure'>Java Library</h6> + <p class='bcode' style='width:500px;'> + juneau-marshall-6.4.0-incubating.jar + </p> + + <h6 class='figure'>OSGi Module</h6> + <p class='bcode' style='width:500px;'> + org.apache.juneau.marshall_6.4.0-incubating.jar + </p> + + <p> + The <code>juneau-marshall</code> library includes easy-to-use and highly customizable serializers and parsers + based around a common API. + They provide support for the following languages: + </p> + <ul> + <li>JSON + <li>XML + <li>HTML + <li>UON (URL-Encoded Object Notation) + <li>URL-Encoding + <li>MessagePack + <li>SOAP/XML + <li>CSV + <li>BSON (coming soon) + <li>YAML (coming soon) + <li>Protobuf (coming soon) + </ul> + <p> + The default serializers can often be used to serialize POJOs in a single line of code: + </p> + <p class='bcode'> + <jc>// A simple bean</jc> + <jk>public class</jk> Person { + <jk>public</jk> String name = <js>"John Smith"</js>; + <jk>public int</jk> age = 21; + } + + Person p = <jk>new</jk> Person(); + + <jc>// Produces: + // "{name:'John Smith',age:21}"</jc> + String laxJson = JsonSerializer.<jsf>DEFAULT_LAX</jsf>.serialize(p); + + <jc>// Produces: + // "{"name":"John Smith","age":21}"</jc> + String strictJson = JsonSerializer.<jsf>DEFAULT</jsf>.serialize(p); + + <jc>// Produces: + // <object> + // <name>John Smith</name> + // <age>21</age> + // </object></jc> + String xml = XmlSerializer.<jsf>DEFAULT_SIMPLE</jsf>.serialize(p); + + <jc>// Produces: + // <table> + // <tr><td>name</td><td>John Smith</td></tr> + // <tr><td>age</td><td>21</td></tr> + // </table></jc> + String html = HtmlSerializer.<jsf>DEFAULT</jsf>.serialize(p); + + <jc>// Same as Html, but wraps it in HTML and BODY elements with page title/description/links:</jc> + String htmlDoc = HtmlDocSerializer.<jsf>DEFAULT</jsf>.serialize(p); + + <jc>// Produces: + // name='John+Smith'&age=21</jc> + String urlEncoding = UrlEncodingSerializer.<jsf>DEFAULT</jsf>.serialize(p); + + <jc>// Produces: + // (name='John Smith',age=21)</jc> + String uon = UonSerializer.<jsf>DEFAULT</jsf>.serialize(p); + + <jc>// Produces: + // 82 A4 name AA 4A John Smith 68 A3 age 15</jc> + <jk>byte</jk>[] messagePack = MsgPackSerializer.<jsf>DEFAULT</jsf>.serialize(p); + </p> + <p> + Parsing back into POJOs is equally simple for any of the supported languages shown above. + Language fragments are also supported. + </p> + <p> + JSON parsing shown here: + </p> + <p class='bcode'> + <jc>// Use one of the predefined parsers.</jc> + ReaderParser parser = JsonParser.<jsf>DEFAULT</jsf>; + + <jc>// Parse a JSON object (creates a generic ObjectMap).</jc> + String json = <js>"{name:'John Smith',age:21}"</js>; + Map m1 = parser.parse(json, Map.<jk>class</jk>); + + <jc>// Parse a JSON string.</jc> + json = <js>"'foobar'"</js>; + String s2 = parser.parse(json, String.<jk>class</jk>); + + <jc>// Parse a JSON number as a Long or Float.</jc> + json = <js>"123"</js>; + Long l3 = parser.parse(json, Long.<jk>class</jk>); + Float f3 = parser.parse(json, Float.<jk>class</jk>); + + <jc>// Parse a JSON object as a bean.</jc> + json = <js>"{name:'John Smith',age:21}"</js>; + Person p4 = parser.parse(json, Person.<jk>class</jk>); + + <jc>// Parse a JSON object as a HashMap<String,Person>.</jc> + json = <js>"{a:{name:'John Smith',age:21},b:{name:'Joe Smith',age:42}}"</js>; + Map<String,Person> m5 = parser.parse(json, HashMap.<jk>class</jk>, String.<jk>class</jk>, Person.<jk>class</jk>); + + <jc>// Parse a JSON object as a HashMap<String,LinkedList<Person>>.</jc> + json = <js>"{a:[{name:'John Smith',age:21},{name:'Joe Smith',age:42}]}"</js>; + Map<String,List<Person>> m6 = parser.parse(json, HashMap.<jk>class</jk>, String.<jk>class</jk>, LinkedList.<jk>class</jk>, Person.<jk>class</jk>); + + <jc>// Parse a JSON array of integers as a Collection of Integers or int[] array.</jc> + json = <js>"[1,2,3]"</js>; + List<Integer> l7 = parser.parse(json, LinkedList.<jk>class</jk>, Integer.<jk>class</jk>); + <jk>int</jk>[] i7 = parser.parse(json, <jk>int</jk>[].<jk>class</jk>); + + <jc>// Parse arbitrary input into ObjectMap or ObjectList objects + // (similar to JSONObject/JSONArray but generalized for all languages).</jc> + json = <js>"{name:'John Smith',age:21}"</js>; + ObjectMap m8a = parser.parse(json, ObjectMap.<jk>class</jk>); + <jk>int</jk> age = m8a.getInt(<js>"age"</js>); + ObjectMap m8b = (ObjectMap)parser.parse(json, Object.<jk>class</jk>); <jc>// Equivalent.</jc> + + json = <js>"[1,true,null]"</js>; + ObjectList l9a = parser.parse(json, ObjectList.<jk>class</jk>); + <jk>boolean</jk> b = l9a.getBoolean(1); + ObjectList l9b = (ObjectList)parser.parse(json, Object.<jk>class</jk>); <jc>// Equivalent.</jc> + </p> + + <h6 class='topic'>Features</h6> + <ul class='spaced-list'> + <li>Serializers can send output directly to Writers, OutputStreams, Files, Strings, or byte arrays. + <li>Parsers can receive input directly from Readers, InputStreams, Files, Strings, or byte arrays. + <li>Parsers can reconstruct arbitrarily complex data structures consisting of maps, collections, beans, and other POJOs. + <li>Serializers and parsers do not use intermediate DOMs! POJOs are serialized directly to streams and parsed back directly to POJOs, making them extremely efficient and fast. + <li>Supported languages are highly-customizable and powerful. For example, JSON support includes: + <ul> + <li>Support for variants such as LAX syntax (unquoted attributes and single quotes). + <li>Support for embedded Javascript comments. + <li>Fully RFC1759 compliant. + <li>20% faster than Jackson. + </ul> + </ul> + <br><hr> + <p> + Serializers and parsers are builder-based. Build from scratch or clone existing instances. Lots of configuration options available for all the languages. + </p> + <p class='bcode'> + <jc>// Create a serializer from scratch using a builder</jc> + JsonSerializer serializer = <jk>new</jk> JsonSerializerBuilder() + .simple() <jc>// Simple mode</jc> + .sq() <jc>// Use single quotes</jc> + .pojoSwaps( <jc>// Swap unserializable classes with surrogate POJOs</jc> + IteratorSwap.<jk>class</jk>, <jc>// Iterators swapped with lists</jc> + ByteArrayBase64Swap.<jk>class</jk>, <jc>// byte[] swapped with base-64 encoded strings</jc> + CalendarSwap.ISO8601DT.<jk>class</jk> <jc>// Calendars swapped with ISO8601-compliant strings</jc> + ) + .beanFilters(MyBeanFilter.<jk>class</jk>) <jc>// Control how bean properties are handled</jc> + .timeZone(TimeZone.<jsf>GMT</jsf>) <jc>// For serializing Calendars</jc> + .locale(Locale.<jsf>JAPAN</jsf>) <jc>// For timezone-specific serialization</jc> + .sortCollections(<jk>true</jk>) <jc>// For locale-specific serialization</jc> + .sortProperties(<jk>true</jk>) <jc>// Various behavior settings</jc> + .trimNullProperties(<jk>true</jk>) + .trimStrings(<jk>true</jk>) + .methodVisibility(<jsf>PROTECTED</jsf>) <jc>// Control which fields/methods are serialized</jc> + .beanDictionary( <jc>// Adds type variables for resolution during parsing</jc> + MyBeanA.<jk>class</jk>, + MyBeanB.<jk>class</jk> + ) + .debug(<jk>true</jk>) <jc>// Add debug output</jc> + .build(); + + <jc>// Clone an existing serializer and modify it to use single-quotes</jc> + JsonSerializer serializer = JsonSerializer.<jsf>DEFAULT</jsf>.builder() + .sq() + .build(); + </p> + <br><br><hr> + <p> + Many POJOs such as primitives, beans, collections, arrays, and classes with various known constructors and methods are serializable out-of-the-box. + For other objects, "transforms" allow you to perform various mutations on them before serialization and after parsing. + </p> + <ul class='spaced-list'> + <li>Transforms + <ul> + <li>Bean filters - Control how bean properties are handled (naming conventions, ordering, visibility,...). + <li>POJO swaps - Replace non-serializable POJOs with serializable equivalents. + <br>Predefined swaps provided for common cases: <code>ByteArrayBase64Swap</code>, 50+ variants of Calendar/Date swaps, <code>Enumeration/Iterator</code> swaps. + </ul> + <li>Annotations + <br>Various annotations available for your POJO classes that are recognized by ALL serializers and parsers: + <br><ja>@Bean</ja>, <ja>@Pojo</ja>, <ja>@BeanIgnore</ja>, <ja>@BeanParam</ja>, <ja>@BeanProperty</ja>, <ja>@NameProperty</ja>, <ja>@ParentProperty</ja> + <br> + <br>Annotations also provided for language-specific behaviors where it makes sense: + <br><ja>@Json</ja>, <ja>@Html</ja>, <ja>@Xml</ja>, <ja>@UrlEncoding</ja> + <br> + <br>All annotations have programmatic equivalents when you don't have access to POJO source. + + <li>Swap methods + <br>By default, various instance and static methods and constructors are automatically detected and supported: + <br><code>valueOf(String)</code>, <code>parse(String)</code>, <code>parseString(String)</code>, <code>forName(String)</code>, <code>forString(String)</code>, + <code>fromString(String)</code>, <code>T(String)</code>, <code>Object swap(BeanSession)</code>, <code>T unswap(BeanSession, T.class)</code> + </ul> + + <ul class='doctree'> + <li class='link'>See <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-marshall.PojoCategories'>POJO Categories</a> for a definition of supported POJOs. + </ul> + + <br><hr> + <p> + UON (URL-Encoded Object Notation) allows JSON-like data structures (OBJECT, ARRAY, NUMBER, BOOLEAN, STRING, NULL) in HTTP constructs (query parameters, form parameters, + headers, URL parts) without violating RFC2396. + This allows POJOs to be converted directly into these HTTP constructs which is not possible in any other language such as JSON. + </p> + <p class='bcode'> + ( + id=1, + name=<js>'John+Smith'</js>, + uri=<js>http://sample/addressBook/person/1</js>, + addressBookUri=<js>http://sample/addressBook</js>, + birthDate=<js>1946-08-12T00:00:00Z</js>, + addresses=@( + ( + uri=<js>http://sample/addressBook/address/1</js>, + personUri=<js>http://sample/addressBook/person/1</js>, + id=<js>1</js>, + street=<js>'100+Main+Street'</js>, + city=<js>Anywhereville</js>, + state=<js>NY</js>, + zip=<js>12345</js>, + isCurrent=<jk>true</jk> + ) + ) + ) + </p> + + <ul class='doctree'> + <li class='link'>See <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/org/apache/juneau/uon/package-summary.html#TOC'>org.apache.juneau.uon</a> for more information. + </ul> + + <br><hr> + <p> + Lots of shortcuts are provided throughout the API to simplify tasks, and the APIs are often useful for debugging and logging purposes as well... + </p> + <p class='bcode'> + <jc>// Create JSON strings from scratch using fluent-style code.</jc> + String jsonObject = <jk>new</jk> ObjectMap().append(<js>"foo"</js>,<js>"bar"</js>).toString(); + String jsonArray = <jk>new</jk> ObjectList().append(<js>"foo"</js>).append(123).append(<jk>null</jk>).toString(); + + <jc>// Create maps and beans directly from JSON.</jc> + Map<String,Object> myMap = <jk>new</jk> ObjectMap(<js>"{foo:'bar'}"</js>); + List<Object> myList = <jk>new</jk> ObjectList(<js>"['foo',123,null]"</js>); + + <jc>// Load a POJO from a JSON file.</jc> + MyPojo myPojo = JsonParser.<jsf>DEFAULT</jsf>.parse(<jk>new</jk> File(<js>"myPojo.json"</js>)); + + <jc>// Serialize POJOs and ignore exceptions (great for logging)</jc> + String json = JsonSerializer.<jsf>DEFAULT_LAX</jsf>.toString(myPojo); + + <jc>// Dump a POJO to the console.</jc> + JsonSerializer.<jsf>DEFAULT_LAX</jsf>.println(myPojo); + + <jc>// Delayed serialization.</jc> + <jc>// (e.g. don't serialize an object if it's not going to be logged).</jc> + logger.log(<jsf>FINE</jsf>, <js>"My POJO was: {0}"</js>, <jk>new</jk> StringObject(myPojo)); + logger.log(<jsf>FINE</jsf>, <js>"My POJO in XML was: {0}"</js>, <jk>new</jk> StringObject(XmlSerializer.<jsf>DEFAULT</jsf>, myPojo)); + + String message = <jk>new</jk> StringMessage(<js>"My POJO in {0}: {1}"</js>, <js>"JSON"</js>, <jk>new</jk> StringObject(myPojo)).toString(); + + <jc>// Create a 'REST-like' wrapper around a POJO.</jc> + <jc>// Allows you to manipulate POJO trees using URIs and GET/PUT/POST/DELETE commands.</jc> + PojoRest pojoRest = <jk>new</jk> PojoRest(myPojo); + pojoRest.get(String.<jk>class</jk>, <js>"addressBook/0/name"</js>); + pojoRest.put(<js>"addressBook/0/name"</js>, <js>"John Smith"</js>); + </p> + <br><br><hr> + <p> + <code>SerializerGroup</code> and <code>ParserGroup</code> classes allow serializers and parsers + to be retrieved by W3C-compliant HTTP <code>Accept</code> and <code>Content-Type</code> values: + </p> + <p class='bcode'> + <jc>// Construct a new serializer group with configuration parameters that get applied to all serializers.</jc> + SerializerGroup sg = <jk>new</jk> SerializerGroupBuilder() + .append(JsonSerializer.<jk>class</jk>, UrlEncodingSerializer.<jk>class</jk>); + .ws() <jc>// or .setUseWhitespace(true)</jc> + .pojoSwaps(CalendarSwap.ISO8601DT.<jk>class</jk>) + .build(); + + <jc>// Find the appropriate serializer by Accept type and serialize our POJO to the specified writer.</jc> + <jc>// Fully RFC2616 compliant.</jc> + sg.getSerializer(<js>"text/invalid, text/json;q=0.8, text/*;q:0.6, *\/*;q=0.0"</js>) + .serialize(myPersonObject, myWriter); + + <jc>// Construct a new parser group with configuration parameters that get applied to all parsers.</jc> + ParserGroup pg = <jk>new</jk> ParserGroupBuilder() + .append(JsonParser.<jk>class</jk>, UrlEncodingParser.<jk>class</jk>); + .pojoSwaps(CalendarSwap.ISO8601DT.<jk>class</jk>) + .build(); + + Person p = pg.getParser(<js>"text/json"</js>).parse(myReader, Person.<jk>class</jk>); + </p> + + <br><br><hr> + + <ul class='doctree'> + <li class='link'>See <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-marshall'>juneau-marshall</a> for more information. + </ul> + </div> + + <!-- ======================================================================================================= --> + <!-- === JUNEAU-MARSHALL-RDF =============================================================================== --> + <!-- ======================================================================================================= --> + + <h5 class='toc' id='juneau-marshall-rdf'>juneau-marshall-rdf</h5> + <div> + <h6 class='figure'>Maven Dependency</h6> + <p class='bcode' style='width:500px;'> + <xt><dependency></xt> + <xt><groupId></xt>org.apache.juneau<xt></groupId></xt> + <xt><artifactId></xt>juneau-marshall-rdf<xt></artifactId></xt> + <xt><version></xt>6.4.0-incubating<xt></version></xt> + <xt></dependency></xt> + </p> + + <h6 class='figure'>Java Library</h6> + <p class='bcode' style='width:500px;'> + juneau-marshall-rdf-6.4.0-incubating.jar + </p> + + <h6 class='figure'>OSGi Module</h6> + <p class='bcode' style='width:500px;'> + org.apache.juneau.marshall.rdf_6.4.0-incubating.jar + </p> + + <p> + The <code>juneau-marshall-rdf</code> library provides additional serializers and parsers for RDF. + These rely on the Apache Jena library to provide support for the following languages: + </p> + <ul> + <li>RDF/XML + <li>RDF/XML-Abbrev + <li>N-Triple + <li>Turtle + <li>N3 + </ul> + <p> + The serializers and parsers work identically to those in <code>juneau-marshall</code>, but are + packaged separately so that you don't need to pull in the Jena dependency unless you need it. + </p> + + <p class='bcode'> + <jc>// A simple bean</jc> + <jk>public class</jk> Person { + <jk>public</jk> String name = <js>"John Smith"</js>; + <jk>public int</jk> age = 21; + } + + <jc>// Serialize a bean to JSON, XML, or HTML</jc> + Person p = <jk>new</jk> Person(); + + <jc>// Produces: + // <rdf:RDF + // xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"; + // xmlns:jp="http://www.apache.org/juneaubp/"; + // xmlns:j="http://www.apache.org/juneau/"> + // <rdf:Description> + // <jp:name>John Smith</jp:name> + // <jp:age>21</jp:age> + // </rdf:Description> + // </rdf:RDF></jc> + String rdfXml = RdfSerializer.<jsf>DEFAULT_XMLABBREV</jsf>.serialize(p); + + <jc>// Produces: + // @prefix jp: <http://www.apache.org/juneaubp/> . + // @prefix j: <http://www.apache.org/juneau/> . + // [] jp:age "21" ; + // jp:name "John Smith" .</jc> + String rdfN3 = RdfSerializer.<jsf>DEFAULT_N3</jsf>.serialize(p); + + <jc>// Produces: + // _:A3bf53c85X3aX157cf407e2dX3aXX2dX7ffd <http://www.apache.org/juneaubp/name> "John Smith" . + // _:A3bf53c85X3aX157cf407e2dX3aXX2dX7ffd <http://www.apache.org/juneaubp/age> "21" .</jc> + String rdfNTriple = RdfSerializer.<jsf>DEFAULT_NTRIPLE</jsf>.serialize(p); + </p> + + <ul class='doctree'> + <li class='link'>See <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-marshall-rdf'>juneau-marshall-rdf</a> for more information. + </ul> + </div> +</body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/e87529b2/content/microservice.html ---------------------------------------------------------------------- diff --git a/content/microservice.html b/content/microservice.html new file mode 100644 index 0000000..f3727c7 --- /dev/null +++ b/content/microservice.html @@ -0,0 +1,227 @@ +<!DOCTYPE html> +<html> +<head> +<style> + @import url("styles/juneau-code.css"); + @import url("styles/juneau-doc.css"); +</style> +</head> +<body> + <!-- =========================================================================================================== --> + <!-- === JUNEAU MICROSERVICE =================================================================================== --> + <!-- =========================================================================================================== --> + + <h5 class='toc' id='juneau-microservice'>juneau-microservice</h5> + <div> + + <p> + Microservices combine all the functionality of the core, server, and client APIs to provide truly powerful + and easy-to-use REST interfaces with minimal overhead. + </p> + + <!-- ======================================================================================================= --> + <!-- === JUNEAU-MICROSERVICE-SERVER ======================================================================== --> + <!-- ======================================================================================================= --> + + <h6 class='toc' id='juneau-microservice-server'>juneau-microservice-server</h6> + <div> + + <h6 class='figure'>Maven Dependency</h6> + <p class='bcode' style='width:500px;'> + <xt><dependency></xt> + <xt><groupId></xt>org.apache.juneau<xt></groupId></xt> + <xt><artifactId></xt>juneau-microservice-server<xt></artifactId></xt> + <xt><version></xt>6.4.0-incubating<xt></version></xt> + <xt></dependency></xt> + </p> + + <h6 class='figure'>Java Library</h6> + <p class='bcode' style='width:500px;'> + juneau-microservice-server-6.4.0-incubating.jar + </p> + + <h6 class='figure'>OSGi Module</h6> + <p class='bcode' style='width:500px;'> + org.apache.juneau.microservice.server_6.4.0-incubating.jar + </p> + + <p> + The Microservice API combines all the features above with a built-in Jetty server to produce a lightweight + REST service packaged as three simple files: + </p> + <ul class='spaced-list'> + <li>An executable jar file that starts up a REST interface in milliseconds. + <li>A configurable <code>jetty.xml</code> file. + <li>An external INI file that can be used to configure your REST resources on the fly. + </ul> + <p> + The microservice API was originally designed for and particularly suited for use in Docker containers. + </p> + <p> + REST microservices can also be started programmatically in existing code: + </p> + <p class='bcode'> + RestMicroservice myRestService = <jk>new</jk> RestMicroservice() + .setConfig(<js>"microservice.cfg"</js>, <jk>false</jk>) + .setJettyXml(<js>"my-jetty.xml"</js>); + myRestService.start(); + URI uri = myRestService.getURI(); + </p> + <p> + The provided microservice.cfg template file gives you a starting point for defining your microservice: + </p> + <p class='bcode'> + <cc>#================================================================================ + # Basic configuration file for SaaS microservices + # Subprojects can use this as a starting point. + #================================================================================</cc> + + <cc>#================================================================================ + # REST settings + #================================================================================</cc> + <cs>[REST]</cs> + + <cc># The location of the jetty.xml file to use for configuring Jetty.</cc> + <ck>jettyXml</ck> = <cv>jetty.xml</cv> + + <cc># Stylesheet to use for HTML views. + # The default options are: + # - styles/juneau.css + # - styles/devops.css + # Other stylesheets can be referenced relative to the servlet package or working + # directory.</cc> + <ck>stylesheet</ck> = <cv>styles/devops.css</cv> + + <cc># What to do when the config file is saved. + # Possible values: + # NOTHING - Don't do anything. + # RESTART_SERVER - Restart the Jetty server. + # RESTART_SERVICE - Shutdown and exit with code '3'.</cc> + <ck>saveConfigAction</ck> = <cv>RESTART_SERVER</cv> + + <cc>#================================================================================ + # Logger settings + # See FileHandler Java class for details. + #================================================================================</cc> + <cs>[Logging]</cs> + + <cc># The directory where to create the log file. + # Default is "."</cc> + <ck>logDir</ck> = <cv>logs</cv> + + <cc># The name of the log file to create for the main logger. + # The logDir and logFile make up the pattern that's passed to the FileHandler + # constructor. + # If value is not specified, then logging to a file will not be set up.</cc> + <ck>logFile</ck> = <cv>microservice.%g.log</cv> + + <cc># Whether to append to the existing log file or create a new one. + # Default is false.</cc> + <ck>append</ck> = + + <cc># The SimpleDateFormat format to use for dates. + # Default is "yyyy.MM.dd hh:mm:ss".</cc> + <ck>dateFormat</ck> = + + <cc># The log message format. + # The value can contain any of the following variables: + # {date} - The date, formatted per dateFormat. + # {class} - The class name. + # {method} - The method name. + # {logger} - The logger name. + # {level} - The log level name. + # {msg} - The log message. + # {threadid} - The thread ID. + # {exception} - The localized exception message. + # Default is "[{date} {level}] {msg}%n".</cc> + <ck>format</ck> = + + <cc># The maximum log file size. + # Suffixes available for numbers. + # See ConfigFile.getInt(String,int) for details. + # Default is 1M.</cc> + <ck>limit</ck> = <cv>10M</cv> + + <cc># Max number of log files. + # Default is 1.</cc> + <ck>count</ck> = <cv>5</cv> + + <cc># Default log levels. + # Keys are logger names. + # Values are serialized Level POJOs.</cc> + <ck>levels</ck> = <cv>{ org.apache.juneau:'INFO' }</cv> + + <cc># Only print unique stack traces once and then refer to them by a simple 8 character hash identifier. + # Useful for preventing log files from filling up with duplicate stack traces. + # Default is false.</cc> + <ck>useStackTraceHashes</ck> = <cv>true</cv> + + <cc># The default level for the console logger. + # Default is WARNING.</cc> + <ck>consoleLevel</ck> = + + <cc>#================================================================================ + # System properties + #-------------------------------------------------------------------------------- + # These are arbitrary system properties that are set during startup. + #================================================================================</cc> + <cs>[SystemProperties]</cs> + + <cc># Configure Jetty for StdErrLog Logging</cc> + <ck>org.eclipse.jetty.util.log.class</ck> = <cv>org.eclipse.jetty.util.log.StrErrLog</cv> + + <cc># Jetty logging level</cc> + <ck>org.eclipse.jetty.LEVEL</ck> = <cv>WARN</cv> + </p> + <p> + This external config file is meant to be used for all of your resource configurations. + APIs are provided in the REST Server APIs for easily accessing these values programmatically, or + by using <js>"$C{...}"</js> variables in your <ja>@RestResource</ja> and <ja>@RestMethod</ja> annotations. + </p> + <p> + Various predefined reusable REST resource classes are provided for accessing log files, viewing and editing the config file, etc... + These allow you to quickly put together sophisticated REST microservices. + </p> + + <ul class='doctree'> + <li class='link'>See <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-microservice-server'>juneau-microservice-server</a> for more information. + </ul> + </div> + + <!-- ======================================================================================================= --> + <!-- === JUNEAU-MICROSERVICE-TEMPLATE ====================================================================== --> + <!-- ======================================================================================================= --> + + <h6 class='toc' id='juneau-microservice-template'>juneau-microservice-template</h6> + <div> + + <h6 class='figure'>Archive File</h6> + <p class='bcode' style='width:500px;'> + my-microservice-6.4.0-incubating.zip + </p> + + <p> + The <code>juneau-microservice-template</code> module is a bare-bones microservice project that can be + used as a starting point for creating your own microservice. + </p> + <p> + The template project ships as a zipped Eclipse project that can be quickly imported into your + workspace as an Eclipse project called "my-microservice". + </p> + <p> + Once loaded, you should see the following project structure: + </p> + <img class='bordered' src='images/juneau-microservice-template.import3.png' style='width:412px'> + <p> + The microservice can be started from the <code>my-microservice.launch</code> file. + It will start up the microservice on port 10000 which you can then view through a browser: + </p> + <img class='bordered' src='images/juneau-microservice-template.import4.png' style='width:467px'> + + <ul class='doctree'> + <li class='link'>See <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-microservice-template'>juneau-microservice-template</a> for more information. + </ul> + </div> + </div> +</body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-juneau-website/blob/e87529b2/content/rest-client.html ---------------------------------------------------------------------- diff --git a/content/rest-client.html b/content/rest-client.html new file mode 100644 index 0000000..b2520c5 --- /dev/null +++ b/content/rest-client.html @@ -0,0 +1,168 @@ +<!DOCTYPE html> +<html> +<head> +<style> + @import url("styles/juneau-code.css"); + @import url("styles/juneau-doc.css"); +</style> +</head> +<body> + <!-- ======================================================================================================= --> + <!-- === JUNEAU-REST-CLIENT ================================================================================ --> + <!-- ======================================================================================================= --> + + <h5 class='toc' id='juneau-rest-client'>juneau-rest-client</h5> + <div> + <h6 class='figure'>Maven Dependency</h6> + <p class='bcode' style='width:500px;'> + <xt><dependency></xt> + <xt><groupId></xt>org.apache.juneau<xt></groupId></xt> + <xt><artifactId></xt>juneau-rest-client<xt></artifactId></xt> + <xt><version></xt>6.4.0-incubating<xt></version></xt> + <xt></dependency></xt> + </p> + + <h6 class='figure'>Java Library</h6> + <p class='bcode' style='width:500px;'> + juneau-rest-client-6.4.0-incubating.jar + </p> + + <h6 class='figure'>OSGi Module</h6> + <p class='bcode' style='width:500px;'> + org.apache.juneau.rest.client_6.4.0-incubating.jar + </p> + + <p> + The REST client API allows you to access REST interfaces using POJOs: + </p> + <p class='bcode'> + <jc>// Create a reusable JSON client.</jc> + RestClient client = <jk>new</jk> RestClientBuilder().build(); + + <jc>// The address of the root resource.</jc> + String url = <js>"http://localhost:10000/systemProperties";</js>; + + <jc>// Do a REST GET against a remote REST interface and convert + // the response to an unstructured ObjectMap object.</jc> + Map m1 = client.doGet(url).getResponse(TreeMap.<jk>class</jk>); + + <jc>// Add some new system properties. + // Use XML as the transport medium.</jc> + client = <jk>new</jk> RestClientBuilder(XmlSerializer.<jk>class</jk>, XmlParser.<jk>class</jk>).build(); + Properties p = <jk>new</jk> Properties(); + p.load(reader); + <jk>int</jk> returnCode = client.doPost(url + <js>"/systemProperties"</js>, p).execute(); + </p> + <p> + The client API uses the same serializers and parsers (and subsequently their flexibility and configurability) as the server side to marshall POJOs back and forth. + </p> + <br><hr> + <p> + The remote proxy interface API allows you to invoke server-side POJO methods on the client side using REST (i.e. RPC over REST): + </p> + <p class='bcode'> + <jc>// Get an interface proxy.</jc> + IAddressBook ab = restClient.getRemoteableProxy(IAddressBook.<jk>class</jk>); + + <jc>// Invoke a method on the server side and get the returned result.</jc> + Person p = ab.createPerson( + <jk>new</jk> Person( + <js>"John Smith"</js>, + <js>"Aug 1, 1999"</js>, + <jk>new</jk> Address(<js>"My street"</js>, <js>"My city"</js>, <js>"My state"</js>, 12345, <jk>true</jk>) + ) + ); + </p> + <p> + Although the client API is not dependent on the <code>juneau-rest-server</code> module, the server + module provides some convenience APIs for exposing remoteable proxies on the server side: + </p> + <ol> + <li>Extending from <code>RemoteableServlet</code>. + <li>Using a <code><ja>@RestMethod</ja>(name=<jsf>PROXY</jsf>)</code> annotation on a Java method. + </ol> + <p> + The <code>RemoteableServlet</code> class is a simple specialized servlet with an abstract <code>getServiceMap()</code> + method to define the server-side POJOs: + </p> + <p class='bcode'> + <ja>@RestResource</ja>( + path=<js>"/remote"</js> + ) + <jk>public class</jk> SampleRemoteableServlet <jk>extends</jk> RemoteableServlet { + + <jc>// Our server-side POJO.</jc> + AddressBook <jf>addressBook</jf> = <jk>new</jk> AddressBook(); + + <ja>@Override</ja> <jc>/* RemoteableServlet */</jc> + <jk>protected</jk> Map<Class<?>,Object> getServiceMap() <jk>throws</jk> Exception { + Map<Class<?>,Object> m = <jk>new</jk> LinkedHashMap<Class<?>,Object>(); + + <jc>// In this simplified example, we expose the same POJO service under two different interfaces. + // One is IAddressBook which only exposes methods defined on that interface, and + // the other is AddressBook itself which exposes all methods defined on the class itself (dangerous!).</jc> + m.put(IAddressBook.<jk>class</jk>, <jf>addressBook</jf>); + m.put(AddressBook.<jk>class</jk>, <jf>addressBook</jf>); + <jk>return</jk> m; + } + } + </p> + <p> + The <code><ja>@RestMethod</ja>(name=<jsf>PROXY</jsf>)</code> approach is easier if you only have a single interface you want to expose. + You simply define a Java method whose return type is an interface, and return the implementation of that interface: + </p> + <p class='bcode'> + <jc>// Our exposed proxy object.</jc> + <ja>@RestMethod</ja>(name=<jsf>PROXY</jsf>, path=<js>"/addressbookproxy/*"</js>) + <jk>public</jk> IAddressBook getProxy() { + <jk>return</jk> addressBook; + } + </p> + <p> + In either case, the proxy communications layer is pure REST. + Parameters passed in on the client side are serialized as an HTTP POST, parsed on the + server side, and then passed to the invocation method. The returned POJO is then marshalled back as an HTTP response. + </p> + <p> + In most cases, you'll want to use JSON or MessagePack as your communications layer since these are the most efficient. + Although remoteable proxies work perfectly well for any of the other supported languages. For example, RPC over Turtle! + </p> + <p> + The parameters and return types of the Java methods can be any of the supported serializable and parsable types in <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-marshall.PojoCategories'>POJO Categories</a>. + This ends up being WAY more flexible than other proxy interfaces since Juneau can handle so may POJO types out-of-the-box. + Most of the time you don't even need to modify your existing Java implementation code. + </p> + <p> + The <code>RemoteableServlet</code> class itself shows how sophisticated REST interfaces can be built on the Juneau REST Servlet + API using very little code. + The class consists of only 53 lines of code, yet is a sophisticated discoverable and self-documenting REST interface. + And since the remote proxy API is built on top of REST, it can be debugged using just a browser. + </p> + <br><hr> + <p> + Remoteable proxies can also be used to define interface proxies against 3rd-party REST interfaces. + This is an extremely powerful feature that allows you to quickly define easy-to-use interfaces against virtually any REST interface. + </p> + <p> + Similar in concept to remoteable services defined above, but in this case we simply define our interface with + special annotations that tell us how to convert input and output to HTTP headers, query parameters, form post parameters, or request/response bodies. + </p> + <p class='bcode'> + <ja>@Remoteable</ja> + <jk>public interface</jk> MyProxyInterface { + + <ja>@RemoteMethod</ja>(httpMethod=<jsf>POST</jsf>, path=<js>"/method"</js>) + String doSomething(<ja>@Header</ja>(<js>"E-Tag"</js>) UUID etag, <ja>@Query</ja>(<js>"debug"</js>) <jk>boolean</jk> debug, <ja>@Body</ja> MyPojo pojo); + } + + RestClient client = <jk>new</jk> RestClientBuilder().build(); <jc>// Default is JSON</jc> + MyProxyInterface p = client.getRemoteableProxy(MyProxyInterface.<jk>class</jk>, <js>"http://hostname/some/rest/interface";</js>); + String response = p.doSomething(UUID.<jsm>generate</jsm>(), <jk>true</jk>, <jk>new</jk> MyPojo()); + </p> + + <ul class='doctree'> + <li class='link'>See <a class='doclink' href='http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-rest-client'>juneau-rest-client</a> for more information. + </ul> + </div> +</body> +</html> \ No newline at end of file
