content/about.html (367 lines of code) (raw):
<!DOCTYPE html>
<html lang="en">
<head>
<style>
@import url("styles/juneau-code.css");
@import url("styles/juneau-doc.css");
</style>
</head>
<body>
<!-- =========================================================================================================== -->
<!-- === ABOUT ================================================================================================= -->
<!-- =========================================================================================================== -->
<h5 class='toc'>About</h5>
<div class='topic'>
<p>
Apache Juneau™ is a single cohesive Java ecosystem consisting of the following parts:
</p>
<table class='styled w900'>
<tr>
<th>Group</th><th>Component</th><th>Description</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'><a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-marshall'>juneau-marshall</a></td>
<td style='padding:10px;'>
POJO marshalling support for JSON, JSON5, XML, HTML, URL-encoding, UON, MessagePack, and CSV using no external module dependencies.
</td>
</tr>
<tr class='dark bb'>
<td class='code'><a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-marshall-rdf'>juneau-marshall-rdf</a></td>
<td style='padding:10px;'>
Extended marshalling support for RDF/XML, N3, N-Tuple, and Turtle.
</td>
</tr>
<tr class='dark bb'>
<td class='code'><a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-dto'>juneau-dto</a></td>
<td style='padding:10px;'>
A variety of predefined DTOs for serializing and parsing languages such as HTML5, Swagger and ATOM.
</td>
</tr>
<tr class='dark bb'>
<td class='code'><a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-config'>juneau-config</a></td>
<td style='padding:10px;'>
A sophisticated configuration file API.
</td>
</tr>
<tr class='dark bb'>
<td class='code'><a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-assertions'>juneau-assertions</a></td>
<td style='padding:10px;'>
A fluent assertions API.
</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'><a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-rest-server'>juneau-rest-server</a></td>
<td style='padding:10px;'>
A universal REST server API for creating Swagger-based self-documenting REST interfaces using POJOs, simply deployed as
one or more top-level servlets in any Servlet 3.1.0+ container.
</td>
</tr>
<tr class='light bb'>
<td class='code'><a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-rest-server-springboot'>juneau-rest-server-springboot</a></td>
<td style='padding:10px;'>
Spring Boot integration.
</td>
</tr>
<tr class='light bb'>
<td class='code'><a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-rest-client'>juneau-rest-client</a></td>
<td style='padding:10px;'>
A universal REST client API for interacting with Juneau or 3rd-party REST interfaces using POJOs and proxy interfaces.
</td>
</tr>
</table>
<p>
Questions via email to <a class='doclink' target='_blank' href='mailto:dev@juneau.apache.org?Subject=Apache%20Juneau%20question'>dev@juneau.apache.org</a> are always welcome.
</p>
<p>
Juneau is packed with features that may not be obvious at first.
Users are encouraged to ask for code reviews by providing links to specific source files such as through GitHub.
Not only can we help you with feedback, but it helps us understand usage patterns to further improve the product.
</p>
</div>
<!-- =========================================================================================================== -->
<!-- === FEATURES ============================================================================================== -->
<!-- =========================================================================================================== -->
<h5 class='toc'>Features</h5>
<div class='topic'>
<p>
The <a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-marshall'>juneau-marshall</a>
and <a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-marshall-rdf'>juneau-marshall-rdf</a>
modules provides memory-efficient typed and untyped POJO serializing and parsing for a variety of languages.
</p>
<p class='bjava'>
<jc>// A simple bean</jc>
<jk>public class</jk> Person {
<jk>public</jk> String <jf>name</jf> = <js>"John Smith"</js>;
<jk>public int</jk> <jf>age</jf> = 21;
}
<jc>// Produces:
// "{"name":"John Smith","age":21}"</jc>
String <jv>json</jv> = Json.<jsm>of</jsm>(<jk>new</jk> Person());
<jc>// Parse back into a bean.</jc>
Person <jv>person</jv> = Json.<jsm>to</jsm>(<jv>json</jv>, Person.<jk>class</jk>);
<jc>// Various other languages.</jc>
String <jv>json5</jv> = Json5.<jsm>of</jsm>(<jv>person</jv>);
String <jv>xml</jv> = Xml.<jsm>of</jsm>(<jv>person</jv>);
String <jv>html</jv> = Html.<jsm>of</jsm>(<jv>person</jv>);
String <jv>urlEncoding</jv> = UrlEncoding.<jsm>of</jsm>(<jv>person</jv>);
String <jv>uon</jv> = Uon.<jsm>of</jsm>(<jv>person</jv>);
String <jv>openApi</jv> = OpenApi.<jsm>of</jsm>(<jv>person</jv>);
String <jv>rdfXml</jv> = RdfXml.<jsm>of</jsm>(<jv>person</jv>);
String <jv>rdfXmlAbbriev</jv> = RdfXmlAbbrev.<jsm>of</jsm>(<jv>person</jv>);
String <jv>n3</jv> = N3.<jsm>of</jsm>(<jv>person</jv>);
String <jv>nTriple</jv> = NTriple.<jsm>of</jsm>(<jv>person</jv>);
String <jv>turtle</jv> = Turtle.<jsm>of</jsm>(<jv>person</jv>);
String <jv>plainText</jv> = PlainText.<jsm>of</jsm>(<jv>person</jv>);
String <jv>csv</jv> = Csv.<jsm>of</jsm>(<jv>person</jv>);
<jk>byte</jk>[] <jv>msgPack</jv> = MsgPack.<jsm>of</jsm>(<jv>person</jv>);
</p>
<p>
The <a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-rest-server'>juneau-rest-server</a>
and <a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-rest-client'>juneau-rest-client</a> libraries
provide server and client side REST capabilities that can be used by themselves, or together to create
simplified yet sophisticated Java-based REST communications layers that completely hide away the complexities
of the REST protocol from end-users.
</p>
<p class='bjava'>
<jc>// Server-side endpoint</jc>
<ja>@Rest</ja>(path=<js>"/petstore"</js>)
<jk>public class</jk> PetStoreRest <jk>extends</jk> BasicRestServlet <jk>implements</jk> BasicUniversalConfig {
<ja>@RestPost</ja>(path=<js>"/pets"</js>, guards=AdminGuard.<jk>class</jk>)
<jk>public</jk> Ok addPet(
<ja>@Content</ja> CreatePet <jv>createPetBean</jv>,
<ja>@Header</ja>(<js>"E-Tag"</js>) UUID <jv>etag</jv>,
<ja>@Query</ja>(<js>"debug"</js>) <jk>boolean</jk> <jv>debug</jv>
) <jk>throws</jk> BadRequest, Unauthorized, InternalServerError {
<jc>// Process request here.</jc>
<jk>return</jk> Ok.<jsf>OK</jsf>; <jc>// Standard 400-OK response.</jc>
}
}
</p>
<p class='bjava'>
<jc>// Client-side Java interface that describes the REST endpoint</jc>
<ja>@Remote</ja>(path=<js>"/petstore"</js>)
<jk>public interface</jk> PetStoreClient {
<ja>@RemotePost</ja>(<js>"/pets"</js>)
Ok addPet(
<ja>@Content</ja> CreatePet <jv>createPet</jv>,
<ja>@Header</ja>(<js>"E-Tag"</js>) UUID <jv>etag</jv>,
<ja>@Query</ja>(<js>"debug"</js>) <jk>boolean</jk> <jv>debug</jv>
) <jk>throws</jk> BadRequest, Unauthorized, InternalServerError;
}
</p>
<p class='bjava'>
<jc>// Use a RestClient with default JSON 5 support and BASIC auth.</jc>
RestClient <jv>client</jv> = RestClient.<jsm>create</jsm>().json5().basicAuth(...).build();
<jc>// Instantiate our proxy interface.</jc>
PetStoreClient <jv>store</jv> = <jv>client</jv>.getRemote(PetStoreClient.<jk>class</jk>, <js>"http://localhost:10000"</js>);
<jc>// Use it to create a pet.</jc>
CreatePet <jv>createPet</jv> = <jk>new</jk> CreatePet(<js>"Fluffy"</js>, 9.99);
Pet <jv>pet</jv> = <jv>store</jv>.addPet(<jv>createPet</jv>, UUID.<jsm>randomUUID</jsm>(), <jk>true</jk>);
</p>
<p>
The <a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-dto'>juneau-dto</a> module
contains several predefined POJOs for generating commonly-used document types that
are designed to be used with the Juneau Marshaller APIs for both serializing and parsing.
For example, you can build HTML DOMs in Java.
</p>
<p class='bjava'>
<jk>import static</jk> org.apache.juneau.dto.html5.HtmlBuilder.*;
<jc>// An HTML table</jc>
Object <jv>mytable</jv> =
<jsm>table</jsm>(
<jsm>tr</jsm>(
<jsm>th</jsm>(<js>"c1"</js>),
<jsm>th</jsm>(<js>"c2"</js>)
),
<jsm>tr</jsm>(
<jsm>td</jsm>(<js>"v1"</js>),
<jsm>td</jsm>(<js>"v2"</js>)
)
);
String <jv>html</jv> = Html.<jsm>of</jsm>(<jv>mytable</jv>);
</p>
<p class='bxml'><xt>
<table>
<tr>
<th><xv>c1</xv></th>
<th><xv>c2</xv></th>
</tr>
<tr>
<td><xv>v1</xv></td>
<td><xv>v2</xv></td>
</tr>
</table>
</xt></p>
<p>
The <a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-config'>juneau-config</a>
module contains a powerful API for creating and using INI-style config files.
</p>
<p class='bini'>
<cc># A set of entries</cc>
<cs>[Section1]</cs>
<cc># An integer</cc>
<ck>key1</ck> = <cv>1</cv>
<cc># A boolean</cc>
<ck>key2</ck> = <cv>true</cv>
<cc># An array</cc>
<ck>key3</ck> = <cv>1,2,3</cv>
<cc># A POJO</cc>
<ck>key4</ck> = <cv>http://bar</cv>
</p>
<p class='bjava'>
<jc>// Create a Config object</jc>
Config <jv>config</jv> = Config.<jsm>create</jsm>().name(<js>"MyConfig.cfg"</js>).build();
<jc>// Read values from section #1</jc>
<jk>int</jk> <jv>key1</jv> = <jv>config</jv>.getInt(<js>"Section1/key1"</js>);
<jk>boolean</jk> <jv>key2</jv> = <jv>config</jv>.getBoolean(<js>"Section1/key2"</js>);
<jk>int</jk>[] <jv>key3</jv> = <jv>config</jv>.getObject(<js>"Section1/key3"</js>, <jk>int</jk>[].<jk>class</jk>);
URL <jv>key4</jv> = <jv>config</jv>.getObject(<js>"Section1/key4"</js>, URL.<jk>class</jk>);
</p>
<p>
The <a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-assertions'>juneau-assertions</a>
module in Juneau is a powerful API for performing fluent style assertions.
</p>
<p class='bjava'>
<jk>import static</jk> org.apache.juneau.assertions.Assertions.*;
<jc>// Check the contents of a string.</jc>
<jc>// "as" methods perform a transformation.</jc>
<jc>// "is" methods perform an assertion.</jc>
<jsm>assertString</jsm>(<js>"foo, bar"</js>)
.asSplit(<js>","</js>)
.asTrimmed()
.is(<js>"foo"</js>, <js>"bar"</js>);
<jc>// Extract a subset of properties from a list of beans and compare using Simplified JSON.</jc>
List<MyBean> <jv>myListOfBeans</jv> = ...;
<jsm>assertBeanList</jsm>(<jv>myListOfBeans</jv>)
.asPropertyMaps(<js>"a,b"</js>)
.asJson().is(<js>"[{a:1,b:'foo'}]"</js>);
</p>
<p>
The <a class='doclink' target='_blank' href='http://juneau.apache.org/site/apidocs-9.0.0/overview-summary.html#juneau-rest-springboot'>juneau-rest-springboot</a>
modules provides servlets for quickly and seemlessly deploying REST endpoints in a Spring Boot application. Has built-in support for
auto-generated Swagger documentation and call statistics on all endpoints.
</p>
<p class='bjava'>
<ja>@SpringBootApplication</ja>
<ja>@Controller</ja>
<jk>public class</jk> App {
<jc>//Entry point method.</jc>
<jk>public static void</jk> main(String[] <jv>args</jv>) {
<jk>new</jk> SpringApplicationBuilder(App.<jk>class</jk>).run(<jv>args</jv>);
}
<jc>// Our root REST bean.
// Note that this must extend from SpringRestServlet to allow use of injection.
// All REST objects are attached to this bean using the Rest.children() annotation.</jc>
<ja>@Bean</ja>
<jk>public</jk> RootResources getRootResources() {
<jk>return new</jk> RootResources();
}
<jc>// Registers our REST bean at the URI root.</jc>
<ja>@Bean</ja>
<jk>public</jk> ServletRegistrationBean<Servlet> getRootServlet(RootResources <jv>rootResources</jv>) {
<jk>return new</jk> ServletRegistrationBean<>(<jv>rootResources</jv>, <js>"/*"</js>);
}
<jc>// Injected child resource.</jc>
<ja>@Bean</ja>
<jk>public</jk> HelloWorldResource getHelloWorldResource() {
<jk>return new</jk> HelloWorldResource();
}
<jc>// Injected child bean used in injected child resource.</jc>
<ja>@Bean</ja>
<jk>public</jk> HelloWorldMessageProvider getHelloWorldMessageProvider() {
<jk>return new</jk> HelloWorldMessageProvider(<js>"Hello Spring injection user!"</js>);
}
}
</p>
<p>
Our root resource servlet serves as a router page. It is defined as follows:
</p>
<p class='bjava'>
<ja>@Rest</ja>(
title=<js>"Root resources"</js>,
description=<js>"Example of a router resource page."</js>,
children={
HelloWorldResource.<jk>class</jk>,
}
)
<ja>@HtmlDocConfig</ja>(
widgets={
ContentTypeMenuItem.<jk>class</jk>
},
navlinks={
<js>"api: servlet:/api"</js>,
<js>"stats: servlet:/stats"</js>,
<js>"$W{ContentTypeMenuItem}"</js>,
<js>"source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
},
aside={
<js>"<div class='text'>"</js>,
<js>" <p>This is an example of a 'router' page that serves as a jumping-off point to child resources.</p>"</js>,
<js>" <p>Resources can be nested arbitrarily deep through router pages.</p>"</js>,
<js>" <p>Note the <span class='link'>API</span> link provided that lets you see the generated swagger doc for this page.</p>"</js>,
<js>" <p>Also note the <span class='link'>STATS</span> link that provides basic usage statistics.</p>"</js>,
<js>" <p>Also note the <span class='link'>SOURCE</span> link on these pages to view the source code for the page.</p>"</js>,
<js>" <p>All content on pages in the UI are serialized POJOs. In this case, it's a serialized array of beans with 2 properties, 'name' and 'description'.</p>"</js>,
<js>" <p>Other features (such as this aside) are added through annotations.</p>"</js>,
<js>"</div>"</js>
},
asideFloat=<js>"RIGHT"</js>
)
<jk>public class</jk> RootResources <jk>extends</jk> BasicSpringRestServletGroup <jk>implements</jk> BasicUniversalConfig {
<jc>// No code! </jc>
}
</p>
<h5 class='figure'>HTML representation</h5>
<img class='bordered w800' src='images/jrss.Overview.RootResources.png'>
<p>
The <c>HelloWorldResource</c> class shows an example of a child resource
defined as an injected bean.
</p>
<p class='bjava'>
<ja>@Rest</ja>(
title=<js>"Hello World"</js>,
description=<js>"An example of the simplest-possible resource"</js>,
path=<js>"/helloWorld"</js>
)
<ja>@HtmlDocConfig</ja>(
aside={
<js>"<div style='max-width:400px' class='text'>"</js>,
<js>" <p>This page shows a resource that simply response with a 'Hello world!' message</p>"</js>,
<js>" <p>The POJO serialized is a simple String.</p>"</js>,
<js>"</div>"</js>
}
)
<jk>public class</jk> HelloWorldResource <jk>extends</jk> BasicRestObject <jk>implements</jk> BasicUniversalConfig {
<ja>@Inject</ja>
<jk>private</jk> HelloWorldMessageProvider <jf>messageProvider</jf>;
<ja>@RestGet</ja>(path=<js>"/*"</js>, summary=<js>"Responds with injected message"</js>)
<jk>public</jk> String sayHello() {
<jk>return</jk> <jf>messageProvider</jf>.get();
}
}
</p>
<h5 class='figure'>HTML representation</h5>
<img class='bordered w800' src='images/jrss.Overview.HelloWorldResource.png'>
<p>
Other features:
</p>
<ul class='spaced-list'>
<li>
Fast memory-efficient serialization.
<li>
Fast, safe, memory-efficient parsing. Parsers are not susceptible to deserialization attacks.
<li>
KISS is our mantra! No auto-wiring. No code generation. No dependency injection. Just add it to your classpath and use it. Extremely simple unit testing!
<li>
Enjoyable to use
<li>
Tiny - ~1MB
<li>
Exhaustively tested
<li>
Lots of up-to-date documentation and examples
<li>
Minimal module dependencies making them optimal for uber-jars
<li>
Built on top of Servlet and Apache HttpClient APIs that allow you to use the newest HTTP/2 features
such as request/response multiplexing and server push.
</ul>
</div>
</body>
</html>