Skip navigation links

Apache Juneau 7.2.1 API

Apache Juneau 7.2.1 Documentation

See: Description

Packages 
Package Description
org.apache.juneau
Marshalling API
org.apache.juneau.annotation
Bean and POJO Annotations
org.apache.juneau.config
Config Support
org.apache.juneau.config.encode
Config Encoding Support
org.apache.juneau.config.event
Config Event Support
org.apache.juneau.config.internal
Internal Utilities
org.apache.juneau.config.store
Config Storage Support
org.apache.juneau.config.vars
Config Predefined SVL Variables
org.apache.juneau.csv
CSV Marshalling Support
org.apache.juneau.dto
Data Transfer Objects
org.apache.juneau.dto.atom
ATOM Data Transfer Objects
org.apache.juneau.dto.cognos
Cognos Data Transfer Objects
org.apache.juneau.dto.html5
HTML5 Data Transfer Objects
org.apache.juneau.dto.jsonschema
JSON-Schema Data Transfer Objects
org.apache.juneau.dto.swagger
Swagger Data Transfer Objects
org.apache.juneau.dto.swagger.ui
Swagger UI Generator
org.apache.juneau.encoders
Encoders
org.apache.juneau.html
HTML Marshalling Support
org.apache.juneau.html.annotation
HTML Marshalling Annotations
org.apache.juneau.http
RFC2616 HTTP Headers
org.apache.juneau.http.annotation
HTTP Part Annotations
org.apache.juneau.httppart
HTTP Part Marshalling Support
org.apache.juneau.httppart.bean
HTTP Part Beans
org.apache.juneau.internal
Internal Utilities
org.apache.juneau.jena
RDF Marshalling Support
org.apache.juneau.jena.annotation
RDF Marshalling Annotations
org.apache.juneau.jso
Java-Serialized-Object Marshalling Support
org.apache.juneau.json
JSON Marshalling Support
org.apache.juneau.json.annotation
JSON Marshalling Annotations
org.apache.juneau.jsonschema
JSON-Schema Marshalling Support
org.apache.juneau.jsonschema.annotation
JSON-Schema Marshalling Annotations
org.apache.juneau.marshall
HTTP Response Beans
org.apache.juneau.microservice
Microservice API
org.apache.juneau.microservice.console
Microservice Console
org.apache.juneau.microservice.resources
Predefined Microservice Resources
org.apache.juneau.microservice.sample
Microservice Samples
org.apache.juneau.msgpack
MessagePack Marshalling Support
org.apache.juneau.oapi
OpenAPI Marshalling Support
org.apache.juneau.parser
Parser API
org.apache.juneau.plaintext
Plaintext Marshalling Support
org.apache.juneau.remote
Remote Interfaces API
org.apache.juneau.remoteable  
org.apache.juneau.rest
REST Server API
org.apache.juneau.rest.annotation
REST Annotations
org.apache.juneau.rest.client
REST Client API
org.apache.juneau.rest.client.mock
REST Client Mock API
org.apache.juneau.rest.client.remote
Remote REST API
org.apache.juneau.rest.converters
REST Response Converters
org.apache.juneau.rest.exception
HTTP Response Exception Beans
org.apache.juneau.rest.helper
REST Interface Helper Classes
org.apache.juneau.rest.jaxrs
JAX-RS Integration
org.apache.juneau.rest.labels  
org.apache.juneau.rest.matchers
Predefined Matchers
org.apache.juneau.rest.mock
REST Server Mock API
org.apache.juneau.rest.remote
Remote service API
org.apache.juneau.rest.remoteable  
org.apache.juneau.rest.reshandlers
HTTP Response Handlers
org.apache.juneau.rest.response
REST Server Utilities
org.apache.juneau.rest.util
REST Server Utilities
org.apache.juneau.rest.vars
Predefined SVL Variables
org.apache.juneau.rest.widget
HTML Widget API
org.apache.juneau.serializer
Serializer API
org.apache.juneau.soap
SOAP/XML Marshalling Support
org.apache.juneau.svl
Simple Variable Language
org.apache.juneau.svl.vars
Predefined SVL Variables
org.apache.juneau.transform
Transform API
org.apache.juneau.transforms
Predefined Transforms
org.apache.juneau.uon
UON Marshalling Support
org.apache.juneau.urlencoding
URL-Encoding Marshalling Support
org.apache.juneau.urlencoding.annotation
URL-Encoding Marshalling Annotations
org.apache.juneau.utils
URL-Encoding Annotations
org.apache.juneau.xml
XML Marshalling Support
org.apache.juneau.xml.annotation
XML Marshalling Annotations
org.apache.juneau.xmlschema
XML-Schema Marshalling Support

Apache Juneau 7.2.1 Documentation

New documentation in 7.2.1

Updated documentation in 7.2.1

Apache Juneau™ is a single cohesive Java ecosystem consisting of the following parts:

Table of Contents
  1. Introduction

    1. Features

    2. Components

  2. juneau-marshall

    1. Serializers

    2. Parsers

    3. Marshalls

    4. HTTP Part Serializers

    5. HTTP Part Parsers

    6. Configurable Properties

      1. Common Serializer Properties

      2. Common Serializer Properties

      3. Common Parser Properties

    7. ObjectMap and ObjectList

    8. SerializerGroups and ParserGroups

    9. Contexts, Builders, Sessions, and PropertyStores

    10. Transforms

      1. PojoSwaps

      2. Per-media-type PojoSwaps

      3. One-way PojoSwaps

      4. @Swap Annotation

      5. Templated Swaps

      6. Swap Methods

      7. Surrogate Classes

      8. @BeanProperty Annotation

      9. @BeanProperty Annotation

      10. @BeanConstructor Annotation

      11. @BeanIgnore Annotation

      12. @NameProperty Annotation

      13. @ParentProperty Annotation

      14. POJO Builders

      15. BeanFilter Class

      16. Interface Filters

      17. Stop Classes

      18. Bypass Serialization using Readers and InputStreams

    11. Bean Names and Dictionaries

      1. Bean Subtypes

    12. Virtual Beans

    13. Non-Tree Models and Recursion Detection

    14. Parsing into Generic Models

    15. Reading Continuous Streams

    16. URIs

    17. Comparison with Jackson

    18. POJO Categories

    19. JSON Details

      1. JSON Methodology

      2. JSON Serializers

      3. Simplified JSON

      4. JSON Parsers

      5. @Json Annotation

      6. JSON-Schema Support

    20. XML Details

      1. XML Methodology

      2. XML Serializers

      3. XML Parsers

      4. @Bean(typeName) Annotation

      5. @Xml(childName) Annotation

      6. @Xml(format) Annotation

      7. Namespaces

      8. XML-Schema Support

    21. HTML Details

      1. HTML Methodology

      2. HTML Serializers

      3. HTML Parsers

      4. @Html Annotation

      5. @Html(render) Annotation

      6. HtmlDocSerializer

      7. BasicHtmlDocTemplate

      8. Custom Templates

      9. HTML-Schema Support

    22. UON Details

      1. UON Methodology

      2. UON Serializers

      3. UON Parsers

    23. URL-Encoding Details

      1. URL-Encoding Methodology

      2. URL-Encoding Serializers

      3. URL-Encoding Parsers

      4. @UrlEncoding Annotation

    24. MessagePack Details

      1. MessagePack Serializers

      2. MessagePack Parsers

    25. OpenAPI Details

      1. OpenAPI Methodology

      2. OpenAPI Serializers

      3. OpenAPI Parsers

    26. Best Practices

  3. juneau-marshall-rdf

    1. RDF Details

      1. RDF Serializers

      2. RDF Parsers

      3. @Rdf Annotation

      4. Namespaces

      5. URI Properties

      6. Root Property

      7. Typed Literals

  4. juneau-dto

    1. HTML5

    2. Atom

    3. Swagger

    4. Swagger UI

  5. juneau-svl

    1. Simple Variable Language

    2. SVL Variables

    3. VarResolvers and VarResolverSessions

    4. Other Notes

  6. juneau-config

    1. Overview

      1. Syntax Rules

    2. Entry Types

      1. Primitive Types

      2. POJOs

      3. Arrays

      4. Collections

      5. Binary Data

    3. Variables

      1. Logic Variables

    4. Encoded Entries

    5. Section Maps

    6. Section Beans

    7. Section Interfaces

    8. Setting Values

      1. File System Changes

      2. Custom Entry Serialization

      3. Setting Values in Bulk

    9. Listeners

    10. Serializing

    11. Config Stores

      1. ConfigMemoryStore

      2. ConfigFileStore

      3. Custom ConfigStores

      4. ConfigStore Listeners

    12. Read-only Configs

    13. Closing Configs

  7. juneau-rest-server

    1. Hello World Example

    2. Class Hierarchy

    3. Instantiation

      1. RestServlet

      2. BasicRestServlet

      3. Children

      4. Router Pages

      5. Resource Resolvers

      6. Lifecycle Hooks

    4. @RestResource

      1. Annotation Inheritance

    5. RestContext

    6. @RestMethod

      1. Java Method Parameters

      2. RestRequest

      3. RestResponse

      4. RequestBody

      5. RequestHeaders

      6. RequestQuery

      7. RequestFormData

      8. @RestMethod(path)

      9. RequestPathMatch

      10. Method Return Types

      11. ReaderResource

      12. StreamResource

      13. @RestMethod(matchers)

      14. Predefined Responses

      15. Predefined Exceptions

      16. Predefined Helper Beans

    7. restRPC

    8. OpenAPI Schema Part Parsing

    9. OpenAPI Schema Part Serializing

    10. HTTP-Part Annotations

      1. @Body

      2. @FormData

      3. @HasFormData

      4. @Query

      5. @HasQuery

      6. @Header

      7. @Path

      8. @Request

      9. @Response

      10. @ResponseHeader

      11. @ResponseStatus

    11. Handling Form Posts

    12. Handling Multi-Part Form Posts

    13. Serializers

    14. Parsers

    15. Properties

    16. Transforms

    17. URIs

    18. Guards

    19. Converters

    20. Messages

    21. Encoders

    22. SVL Variables

    23. Configuration Files

    24. Static files

    25. Client Versioning

    26. RestInfoProvider

      1. BasicRestInfoProvider

    27. Swagger

      1. BasicRestServlet

      2. Basic Swagger Info

      3. Tags

      4. Operations

      5. Parameters

      6. Parameter Examples

      7. Responses

      8. Response Examples

      9. Models

      10. SwaggerUI.css

    28. @HtmlDoc

      1. User Interfaces (UI) vs. Developer Interfaces (DI)

      2. Widgets

      3. Predefined Widgets

      4. UI Customization

      5. Stylesheets

    29. Default Headers

    30. Logging and Error Handling

    31. HTTP Status Codes

    32. Overloading HTTP Methods

    33. Built-in Parameters

    34. Custom Serializers and Parsers

    35. Using with OSGi

    36. Serverless Unit Testing

    37. Using with Spring and Injection frameworks

    38. Using HTTP/2 features

    39. Other Notes

  8. juneau-rest-server-jaxrs

    1. Juneau JAX-RS Provider

  9. juneau-rest-client

    1. REST Proxies

      1. @RemoteResource

      2. @RemoteMethod

      3. @Body

      4. @FormData

      5. @Query

      6. @Header

      7. @Path

      8. @Request

      9. @Response

      10. Dual-purpose (end-to-end) interfaces

    2. SSL Support

    3. Authentication

      1. BASIC Authentication

      2. FORM-based Authentication

      3. OIDC Authentication

    4. Using Response Patterns

    5. Piping Response Output

    6. Debugging

    7. Logging

    8. Interceptors

    9. Serverless Unit Testing

    10. Other Useful Methods

  10. juneau-microservice-server

    1. Microservice Introduction

    2. Getting Started

      1. Installing in Eclipse

      2. Running in Eclipse

      3. Building and Running from Command-Line

    3. Manifest File

      1. Manifest API

    4. Config

      1. Config File API

    5. Resource Classes

    6. Predefined Resource Classes

    7. RestMicroservice

      1. Extending RestMicroservice

    8. UI Customization

  11. juneau-examples-core

  12. juneau-examples-rest

    1. RootResources

    2. HelloWorldResource

    3. PetStoreResource

    4. DtoExamples

    5. PhotosResource

    6. SqlQueryResource

    7. ConfigResource

    8. LogsResource

  13. Security Best-Practices

    1. juneau-marshall

    2. juneau-svl

    3. juneau-rest-server

1 - Introduction

Apache Juneau™ is a single cohesive Java ecosystem consisting of the following parts:

  • juneau-marshall - A universal toolkit for marshalling POJOs to a wide variety of content types using a common framework with no external library dependencies.
  • juneau-dto - A variety of predefined DTOs for serializing and parsing languages such as HTML5, Swagger and ATOM.
  • juneau-svl - A simple yet powerful variable replacement language API.
  • juneau-config - A sophisticated configuration file API.
  • juneau-rest-server - 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.
  • juneau-rest-client - A universal REST client API for interacting with Juneau or 3rd-party REST interfaces using POJOs and proxy interfaces.
  • juneau-microservice - A REST microservice API that combines all the features above with a simple configurable Jetty server for creating lightweight standalone REST interfaces that start up in milliseconds.

Questions via email to dev@juneau.apache.org are always welcome.

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.

History

Juneau started off as a popular internal IBM toolkit called Juno. Originally used for serializing POJOs to and from JSON, it later expanded in scope to include a variety of content types, and then later REST servlet, client, and microservice APIs. It's use grew to more than 50 projects and was one of the most popular community source projects within IBM.

In June of 2016, the code was donated to the Apache Foundation under the project Apache Juneau where it has continued to evolve to where it is today.

1.1 - Features

  • 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!
  • Enjoyable to use
  • Tiny - ~1MB
  • Exhaustively tested
  • Lots of up-to-date documentation and examples
  • Minimal library dependencies:
    • juneau-marshall, juneau-dto, juneau-svl, juneau-config - No external dependencies. Entirely self-contained.
    • juneau-marshall-rdf - Optional RDF support. Requires Apache Jena 2.7.1+.
    • juneau-rest-server - Any Servlet 3.1.0+ container.
    • juneau-rest-client - Apache HttpClient 4.5+.
    • juneau-microservice - Eclipse Jetty.
  • 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.

1.2 - Components

We've strived to keep prerequisites to an absolute minimum in order to make adoption as easy as possible.

The library consists of the following artifacts found in the Maven group "org.apache.juneau":

CategoryMaven ArtifactsDescriptionPrereqs
juneau-core juneau-marshall Serializers and parsers for:
  • JSON
  • XML
  • HTML
  • UON
  • URL-Encoding
  • MessagePack
  • SOAP/XML
  • CSV
  • BSON (coming soon)
  • YAML (coming soon)
  • Protobuf (coming soon)
  • Amazon Ion (coming soon)
  • Java 7
juneau-marshall-rdf Serializers and parsers for:
  • RDF/XML
  • RDF/XML-Abbrev
  • N-Triple
  • Turtle
  • N3
  • Java 7
  • Apache Jena 2.7.1
juneau-dto Data Transfer Objects for:
  • HTML5
  • Atom
  • Cognos
  • JSON-Schema
  • Swagger 2.0
  • Java 7
juneau-svl Simple Variable Language API
  • Java 7
juneau-config Configuration file API
  • Java 7
juneau-rest juneau-rest-server REST Servlet API
  • Java 7
  • Servlet 3.1
juneau-rest-server-jaxrs Optional JAX-RS support
  • Java 7
  • JAX-RS 2.0
juneau-rest-client REST Client API
  • Java 7
  • Apache HttpClient 4.5.3
juneau-microservice juneau-microservice-server REST Microservice Server API
  • Java 8
  • Eclipse Jetty 9.4.3
juneau-microservice-template Developer template project
  • Java 8
  • Eclipse Jetty 9.4.3
juneau-examples juneau-examples-core Core code examples
juneau-example-rest REST code examples
juneau-all juneau-all Combination of the following:
  • juneau-marshall
  • juneau-dto
  • juneau-svl
  • juneau-config
  • juneau-rest-server
  • juneau-rest-client
  • Java 7
  • Servlet 3.1
  • Apache HttpClient 4.5.3

The current version of Juneau is 7.2.1. The easiest way to pull in the library is through the following maven dependency:

<dependency> <groupId>org.apache.juneau</groupId> <artifactId>juneau-all</artifactId> <version>7.2.1</version> </dependency>

If you would like to work with the bleeding-edge code, you can access the 7.2.1 version through the following repository:

<pluginRepositories> <pluginRepository> <id>apache.snapshots</id> <url>http://repository.apache.org/snapshots/</url> <snapshots> <enabled>true</enabled> <updatePolicy>always</updatePolicy> </snapshots> </pluginRepository> </pluginRepositories>

Each of the components are also packaged as stand-alone OSGi modules.

2 - juneau-marshall

Maven Dependency

<dependency> <groupId>org.apache.juneau</groupId> <artifactId>juneau-marshall</artifactId> <version>7.2.1</version> </dependency>

Java Library

juneau-marshall-7.2.1.jar

OSGi Module

org.apache.juneau.marshall_7.2.1.jar

The juneau-marshall artifact contains the API for defining serializers and parsers, and marshalling support for JSON, XML, HTML, URL-Encoding, UON and others.

It also defines many convenience utility classes used throughout the framework.

2.1 - Serializers

One of the goals of Juneau was to make serialization as simple as possible. In a single line of code, you should be able to serialize and parse most POJOs. Despite this simplicity, Juneau provides lots of extensibility and configuration properties for tailoring how POJOs are serialized and parsed.

The built-in serializers in Juneau are fast, efficient, and highly configurable. They work by serializing POJOs directly to streams instead of using intermediate Document Object Model objects.

In most cases, you can serialize objects in one line of code by using one of the default serializers:

// A simple bean public class Person { public String name = "John Smith"; public int age = 21; } // Serialize to JSON, XML, or HTML Person p = new Person(); // Produces: // "{\"name\":\"John Smith\",\"age\":21}" String json = JsonSerializer.DEFAULT.serialize(p); // Produces: // "{name:'John Smith',age:21}" String json = SimpleJsonSerializer.DEFAULT.serialize(p); // Produces: // <object> // <name>John Smith</name> // <age>21</age> // </object> String xml = XmlSerializer.DEFAULT.serialize(p); // Produces: // <table> // <tr><th>key</th><th>value</th></tr> // <tr><td>name</td><td>John Smith</td></tr> // <tr><td>age</td><td>21</td></tr> // </table> String html = HtmlSerializer.DEFAULT.serialize(p); // Produces: // "(name='John Smith',age=21)" String uon = UonSerializer.DEFAULT.serialize(p); // Produces: // "name='John+Smith'&age=21" String urlencoding = UrlEncodingSerializer.DEFAULT.serialize(p); // Produces: // 82 A4 6E 61 6D 65 AA 4A 6F 68 6E 20 53 6D 69 74 68 A3 61 67 65 15 byte[] b = MsgPackSerializer.DEFAULT.serialize(p);

In addition to the default serializers, customized serializers can be created using various built-in options:

// Use one of the default serializers to serialize a POJO String json = JsonSerializer.DEFAULT.serialize(someObject); // Create a custom serializer for lax syntax using single quote characters JsonSerializer serializer = JsonSerializer.create().simple().sq().build(); // Clone an existing serializer and modify it to use single-quotes JsonSerializer serializer = JsonSerializer.DEFAULT.builder().sq().build(); // Serialize a POJO to JSON String json = serializer.serialize(someObject);

Default serialization support is provided for Java primitives, Maps, Collections, beans, and arrays.
Extensible support for other data types such as Calendars, Dates, Iterators is available through the use of POJO swaps (described later).

The class hierarchy for the serializers (excluding specialized subclasses) are:

2.2 - Parsers

Parsers work by parsing input directly into POJOs instead of having to create intermediate Document Object Models. This allows them to parse input with minimal object creation.

Like the serializers, you can often parse objects in one line of code by using one of the default parsers:

// Use one of the predefined parsers. Parser parser = JsonParser.DEFAULT; // Parse a JSON object as a bean. String json = "{name:'John Smith',age:21}"; Person p = parser.parse(json, Person.class); // Or parse it into a generic Map. Map m1 = parser.parse(json, Map.class); // Parse a JSON string. json = "'foobar'"; String s2 = parser.parse(json, String.class); // Parse a JSON number as a Long or Float. json = "123"; Long l3 = parser.parse(json, Long.class); Float f3 = parser.parse(json, Float.class); // Parse a JSON object as a HashMap<String,Person>. json = "{a:{name:'John Smith',age:21},b:{name:'Joe Smith',age:42}}"; Map<String,Person> m4 = parser.parse(json, HashMap.class, String.class, Person.class) // Parse a JSON object as a HashMap<String,LinkedList<Person>>. json = "{a:[{name:'John Smith',age:21},{name:'Joe Smith',age:42}]}"; Map<String,List<Person>> m5 = parser.parse(json, HashMap.class, String.class, LinkedList.class, Person.class) // Parse a JSON array of integers as a Collection of Integers or int[] array. json = "[1,2,3]"; List<Integer> l6 = parser.parse(json, LinkedList.class, Integer.class); int[] i7 = parser.parse(json, int[].class);

The parsers can also be used to populating existing bean and collection objects:

// Use one of the predefined parsers. Parser parser = JsonParser.DEFAULT; // Populate the properties on an existing bean from a JSON object. String json = "{name:'John Smith',age:21}"; Person p = new Person(); parser.parseIntoBean(json, p); // Populate an existing list from a JSON array of numbers. json = "[1,2,3]"; List<Integer> l2 = new LinkedList<Integer>(); parser.parseIntoCollection(json, l2, Integer.class); // Populate an existing map from a JSON object containing beans. json = "{a:{name:'John Smith',age:21},b:{name:'Joe Smith',age:42}}"; Map<String,Person> m3 = new TreeMap<String,Person>(); parser.parseIntoMap(json, m3, String.class, Person.class);

  • In the example above, we're parsing "lax" JSON (single quotes, unquoted attributes). The JSON parser can handle any valid JSON syntax (such as quoted or unquoted attributes, single or double quotes).
    It can also handle JSON fragments and embedded Javascript comments. Many of the JSON examples provided will use lax syntax which is easier to read since we don't have to deal with escapes.

The class hierarchy for the parsers (excluding specialized subclasses) are:

2.3 - Marshalls

Marshalls are simple pairings of a Serializer and Parser with convenience methods for serializing and parsing POJOs.

Marshalls are often cleaner to use on-the-fly since they have simplified names.
The following shows the Json marshall in action:

Examples:

// Using instance. Json json = new Json(); MyPojo myPojo = json.read(string, MyPojo.class); String string = json.write(myPojo);

// Using DEFAULT instance. MyPojo myPojo = Json.DEFAULT.read(string, MyPojo.class); String string = Json.DEFAULT.write(myPojo);

Marshalls exist for all supported languages.

2.4 - HTTP Part Serializers

There is a separate set of serializers for serializing HTTP parts (query, form-data, headers, path variables, and plain-text request bodies).
The distinction is that these are designed to serialize directly to strings based on Open-API schema information.

// Schema information about our part. HttpPartSchema schema = HttpPartSchema .create("array") .collectionFormat("pipes") .items( HttpPartSchema .create("array") .collectionFormat("csv") .items( HttpPartSchema.create("integer","int64") ) ) .build(); // Our value to serialize Object value = new long[][]{{1,2,3},{4,5,6},{7,8,9}}; // Produces "1,2,3|4,5,6|7,8,9" String output = OpenApiSerializer.DEFAULT.serialize(HttpPartType.HEADER, schema, value);

The class hierarchy for the part serializers are:

2.5 - HTTP Part Parsers

There is a separate set of parsers for parsing HTTP parts (query, form-data, headers, path variables, and plain-text request bodies).
The distinction is that these are designed to parse directly from strings based on Open-API schema information.

// Schema information about our part. HttpPartSchema schema = HttpPartSchema .create("array") .collectionFormat("pipes") .items( HttpPartSchema .create("array") .collectionFormat("csv") .items( HttpPartSchema.create("integer","int64") ) ) .build(); // Our input to parse. String input = "1,2,3|4,5,6|7,8,9"; // Produces "[[1,2,3],[4,5,6],[7,8,9]] long[][] value = OpenApiParser.DEFAULT.parse(HttpPartType.HEADER, schema, input, long[][].class);

The class hierarchy for the part serializers are:

2.6 - Configurable Properties

Serializers and parsers have a wide variety of configurable properties.
They all extend from the BeanContextBuilder class that allows you to easily construct new instances from scratch or build upon existing instances.
For example, the following code shows how to configure a JSON serializer:

WriterSerializer s = JsonSerializer .create() // Create a JsonSerializerBuilder .simple() // Simple mode .ws() // Use whitespace .sq() // Use single quotes .build(); // Create a JsonSerializer

Configurable settings can also be set declaratively.
The following produces the same serializer.

WriterSerializer s = JsonSerializer .create() .set(JSON_simpleMode, true) .set(SERIALIZER_useWhitespace, true) .set(SERIALIZER_quoteChar, "'") .build();

However, each of the serializers and parsers already contain reusable instances with common configurations.
For example, JSON has the following predefined reusable serializers and parsers:

These can be used directly, as follows:

// Serialize a POJO to LAX JSON. String json = SimpleJsonSerializer.DEFAULT.serialize(myPojo);

For performance reasons, serializers and parsers are immutable. However, they can be 'copied' and modified using the builder() method.

// Clone and customize an existing serializer. WriterSerializer s = SimpleJsonSerializer.DEFAULT .builder() // Create a new builder with copied settings. .quoteChar('"') // Use a different quote character. .build();

2.6.1 - Common Serializer Properties

2.6.2 - Common Serializer Properties

2.6.3 - Common Parser Properties

2.7 - ObjectMap and ObjectList

The ObjectMap and ObjectList classes are generic Java representations of JSON objects and arrays. These classes can be used to create "unstructured" models for serialization (as opposed to "structured" models consisting of beans). If you want to quickly generate JSON/XML/HTML from generic maps/collections, or parse JSON/XML/HTML into generic maps/collections, these classes work well.

These classes extend directly from the following JCF classes:

The ObjectMap and ObjectList classes are very similar to the JSONObject and JSONArray classes found in other libraries. However, the names were chosen because the concepts of Maps and Lists are already familiar to Java programmers, and these classes can be used with any of the serializers or parsers.

These object can be serialized in one of two ways:

  1. Using the provided ObjectMap.serializeTo(java.io.Writer) or ObjectList.serializeTo(java.io.Writer) methods.
  2. Passing them to one of the Serializer serialize methods.
  3. Simply calling the ObjectMap.toString() or ObjectList.toString() methods which will serialize it as Simplified JSON.

Any valid JSON can be parsed into an unstructured model consisting of generic ObjectMap and ObjectList objects.
(In theory, any valid XML can also be parsed into an unstructured model, although this has not been officially 'tested')

// Parse an arbitrary JSON document into an unstructered data model // consisting of ObjectMaps, ObjectLists, and java primitive objects. Parser parser = JsonParser.DEFAULT; String json = "{a:{name:'John Smith',age:21},b:{name:'Joe Smith',age:42}}"; ObjectMap m = parser.parse(json, ObjectMap.class); // Use ObjectMap API to extract data from the unstructured model. int johnSmithAge = m.getObjectMap("a").getInt("age"); // Convert it back into JSON. json = JsonSerializer.DEFAULT.serialize(m); // Or convert it to XML. String xml = XmlSerializer.DEFAULT.serialize(m); // Or just use toString(). json = m.toString();

The ObjectMap and ObjectList classes have many convenience features:

// Convert the map to a bean. MyBean m = objectMap.cast(MyBean.class); // Find entries by multiple keys. MyBean m = objectMap.find(MyBean.class, "key1", "key2"); // Fluent-style appenders. objectMap.append("key1", "val1").append("key2", "val2"); // REST-like functions for manipulating nodes in the data structure using URL-like notation. objectMap.getAt("foo/bar/myBean", MyBean.class); objectMap.putAt("foo/bar/myBean", MyBean.class); objectMap.postAt("foo/bar/myListOfBeans", MyBean.class); objectMap.deleteAt("foo/bar/myBean"); // Copy with inclusion or exclusion. ObjectMap m2 = objectMap.include("key1", "key2", "key3"); ObjectMap m3 = objectMap.exclude("key1", "key2", "key3"); // Serialize using another serializer. String xml = objectMap.serializeTo(XmlSerializer.DEFAULT); // Nested maps. objectMap.setInner(objectMapInner);

  • As a general rule, if you do not specify a target type during parsing, or if the target type cannot be determined through reflection, the parsers automatically generate ObjectMaps and ObjectLists.

2.8 - SerializerGroups and ParserGroups

Above the serializers and parsers are the SerializerGroup and ParserGroup classes. These classes allow serializers and parsers to be retrieved by W3C-compliant HTTP Accept and Content-Type values...

// Construct a new serializer group with configuration parameters that get applied to all serializers. SerializerGroup sg = SerializerGroup.create() .append(JsonSerializer.class, UrlEncodingSerializer.class); .ws // or .useWhitespace(true) .pojoSwaps(CalendarSwap.ISO8601DT.class) .build(); // Find the appropriate serializer by Accept type and serialize our POJO to the specified writer. sg.getSerializer("text/invalid, text/json;q=0.8, text/*;q:0.6, *\/*;q=0.0") .serialize(myPersonObject, myWriter); // Construct a new parser group with configuration parameters that get applied to all parsers. ParserGroup pg = ParserGroup.create() .append(JsonSerializer.class, UrlEncodingSerializer.class); .pojoSwaps(CalendarSwap.ISO8601DT.class) .build(); Person p = pg.getParser("text/json").parse(myReader, Person.class);

The REST servlet API builds upon the SerializerGroup and ParserGroup classes to provide annotated REST servlets that automatically negotiate the HTTP media types and allow the developer to work with requests and responses as POJOs.

2.9 - Contexts, Builders, Sessions, and PropertyStores

All the serializers, parsers, and REST server/client classes use the following design pattern:

  • Context - A thread-safe read-only object.
    • Heavy to construct and designed to be cached and reused.
    • Created by ContextBuilder classes.
    • Examples: BeanContext, JsonSerializer
  • Session - A non-thread-safe single-use object with configuration combined from context and runtime args such as locale/timezone.
    • Lightweight objects that take a minimum amount of time to instantiate and are not typically reused.
    • Created by Context objects.
    • Examples: BeanSession, JsonSerializerSession
  • PropertyStore - A thread-safe read-only set of configuration properties.
    • Heavier to create than Sessions but lighter than Contexts.
    • Each Context contains one PropertyStore that defines all the configuration about that object.
    • Created by PropertyStoreBuilder classes.

For example, the class hierarchy for JsonSerializer is:

Each context object in the hierarchy define properties that can be stored in a PropertyStore such as SERIALIZER_useWhitespace or JSON_simpleMode.

The class hierarchy for JsonSerializerBuilder is:

The class hierarchy for JsonSerializerSession is:

The general idea behind a PropertyStore is to serve as a reusable configuration of an artifact (such as a serializer) such that the artifact can be cached and reused if the property stores are 'equal'.

For example, two serializers of the same type created with the same configuration will always end up being the same serializer:

// Two serializers created with identical configurations will always be the same copy. WriterSerializer s1 = JsonSerializer.create().pojoSwaps(MySwap.class).simple().build(); WriterSerializer s2 = JsonSerializer.create().set(JSON_simpleMode, true).pojoSwaps(MySwap.class).build(); assert(s1 == s2);

This has the effect of significantly improving performance especially if you're creating many serializers and parsers.

The PropertyStoreBuilder class is used to build up and instantiate immutable PropertyStore objects.

In the example above, the property store being built looks like the following:

PropertyStore ps = PropertyStore .create() .set("BeanContext.pojoSwaps.lc", MySwap.class) .set("JsonSerializer.simpleMode.b", true) .build();

Property stores are immutable, comparable, and their hashcodes are calculated exactly one time. That makes them particularly suited for use as hashmap keys, and thus for caching reusable serializers and parsers.

Refer to the PropertyStore javadoc for a detailed explaination on how property stores work.

2.10 - Transforms

By default, the Juneau framework can serialize and parse a wide variety of POJOs out-of-the-box.
However, two special classes are provided tailor how certain Java objects are handled by the framework.
These classes are:

  • BeanFilter - Transforms that alter the way beans are handled.
  • PojoSwap - Transforms that swap non-serializable POJOs with serializable POJOs during serialization (and optionally vis-versa during parsing).
    • StringSwap - Convenience subclass for swaps that convert objects to strings.
    • MapSwap - Convenience subclass for swaps that convert objects to maps.

Transforms are added to serializers and parsers (and REST clients) using the following configuration properties:

Annotations are also provided for specifying transforms directly on classes and methods (all described in later sections):

  • @Swap - Used to tailor how non-bean POJOs get interpreted by the framework.
  • @Bean - Used to tailor how beans get interpreted by the framework.
  • @BeanConstructor - Maps constructor arguments to property names on beans with read-only properties.
  • @BeanIgnore - Ignore classes, fields, and methods from being interpreted as bean or bean components.
  • @BeanProperty - Used to tailor how bean properties get interpreted by the framework.
  • @NameProperty - Identifies a setter as a method for setting the name of a POJO as it's known by its parent object.
  • @ParentProperty - Identifies a setter as a method for adding a parent reference to a child object.
  • @URI - Used to identify a class or bean property as a URI.

2.10.1 - PojoSwaps

PojoSwaps are a critical component of Juneau. They allow the serializers and parsers to handle Java objects that wouldn't normally be serializable.

Swaps are, simply put, 'object swappers' that swap in serializable objects for non-serializable ones during serialization, and vis-versa during parsing.

Some examples of non-serializable POJOs are File, Reader, Iterable, etc... These are classes that aren't beans and cannot be represented as simple maps, collections, or primitives.

In the following example, we introduce a PojoSwap that will swap in ISO8601 strings for Date objects:

// Sample swap for converting Dates to ISO8601 strings. public class MyDateSwap extends PojoSwap<Date,String> { // ISO8601 formatter. private DateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ"); // Converts a Date object to an ISO8601 string. @Override /* PojoSwap */ public String swap(BeanSession session, Date o) { return format.format(o); } // Converts an ISO8601 string to a Date object. @Override /* PojoSwap */ public Date unswap(BeanSession session, String o, ClassMeta hint) throws Exception { return format.parse(o); } }

The swap can then be associated with serializers and parsers like so:

// Sample bean with a Date field. public class MyBean { public Date date = new Date(112, 2, 3, 4, 5, 6); } // Create a new JSON serializer, associate our date swap with it, and serialize a sample bean. WriterSerializer s = JsonSerializer.create().simple().pojoSwaps(MyDateSwap.class).build(); String json = s.serialize(new MyBean()); // == "{date:'2012-03-03T04:05:06-0500'}" // Create a JSON parser, associate our date swap with it, and reconstruct our bean (including the date). ReaderParser p = JsonParser.create().pojoSwaps(MyDateSwap.class).build(); MyBean bean = p.parse(json, MyBean.class); int day = bean.date.getDay(); // == 3

The BeanMap.get(Object) and BeanMap.put(String,Object) methods will automatically convert to swapped values as the following example shows:

// Create a new bean context and add our swap. BeanContext bc = BeanContext.create().pojoSwaps(MyDateSwap.class).build(); // Create a new bean. MyBean myBean = new MyBean(); // Wrap it in a bean map. BeanMap<Bean> beanMap = bc.forBean(myBean); // Use the get() method to get the date field as an ISO8601 string. String date = (String)beanMap.get("date"); // == "2012-03-03T04:05:06-0500" // Use the put() method to set the date field to an ISO8601 string. beanMap.put("date", "2013-01-01T12:30:00-0500"); // Set it to a new value. // Verify that the date changed on the original bean. int year = myBean.date.getYear(); // == 113

Another example of a PojoSwap is one that converts byte[] arrays to BASE64-encoded strings:

public class ByteArrayBase64Swap extends StringSwap<byte[]> { @Override /* StringSwap */ public String swap(byte[] b) throws Exception { ByteArrayOutputStream baos = new ByteArrayOutputStream(); OutputStream b64os = MimeUtility.encode(baos, "base64"); b64os.write(b); b64os.close(); return new String(baos.toByteArray()); } @Override /* StringSwap */ public byte[] unswap(String s, ClassMeta<?> hint) throws Exception { byte[] b = s.getBytes(); ByteArrayInputStream bais = new ByteArrayInputStream(b); InputStream b64is = MimeUtility.decode(bais, "base64"); byte[] tmp = new byte[b.length]; int n = b64is.read(tmp); byte[] res = new byte[n]; System.arraycopy(tmp, 0, res, 0, n); return res; } }

The following example shows the BASE64 swap in use:

// Create a JSON serializer and register the BASE64 encoding swap with it. WriterSerializer s = JsonSerializer.create().simple().pojoSwaps(ByteArrayBase64Swap.class).build(); ReaderParser p = JsonParser.create().pojoSwaps(ByteArrayBase64Swap.class).build(); byte[] bytes = {1,2,3}; String json = s.serialize(bytes); // Produces "'AQID'" bytes = p.parse(json, byte[].class); // Reproduces {1,2,3} byte[][] bytes2d = {{1,2,3},{4,5,6},null}; json = s.serialize(bytes2d); // Produces "['AQID','BAUG',null]" bytes2d = p.parse(json, byte[][].class); // Reproduces {{1,2,3},{4,5,6},null}

Several PojoSwaps are already provided for common Java objects:

In particular, the CalendarSwap and DateSwap transforms provide a large number of customized swaps to ISO, RFC, or localized strings.

Swaps have access to the session locale and timezone through the BeanSession.getLocale() and BeanSession.getTimeZone() methods.
This allows you to specify localized swap values when needed.

If using the REST server API, the locale and timezone are set based on the Accept-Language and Time-Zone headers on the request.

  • The 'swapped' class type must be a serializable type.
    See the definition for Category 4 objects in POJO Categories.

2.10.2 - Per-media-type PojoSwaps

Swaps can also be defined per-media-type.

The PojoSwap.forMediaTypes() method can be overridden to provide a set of media types that the swap is invoked on.
It's also possible to define multiple swaps against the same POJO as long as they're differentiated by media type.
When multiple swaps are defined, the best-match media type is used.

In the following example, we define 3 swaps against the same POJO. One for JSON, one for XML, and one for all other types.

public class PojoSwapTest { public static class MyPojo {} public static class MyJsonSwap extends PojoSwap<MyPojo,String> { @Override /* PojoSwap */ public MediaType[] forMediaTypes() { return MediaType.forStrings("*/json"); } @Override /* PojoSwap */ public String swap(BeanSession session, MyPojo o) throws Exception { return "It's JSON!"; } } public static class MyXmlSwap extends PojoSwap<MyPojo,String> { @Override /* PojoSwap */ public MediaType[] forMediaTypes() { return MediaType.forStrings("*/xml"); } @Override /* PojoSwap */ public String swap(BeanSession session, MyPojo o) throws Exception { return "It's XML!"; } } public static class MyOtherSwap extends PojoSwap<MyPojo,String> { @Override /* PojoSwap */ public MediaType[] forMediaTypes() { return MediaType.forStrings("*/*"); } @Override /* PojoSwap */ public String swap(BeanSession session, MyPojo o) throws Exception { return "It's something else!"; } } @Test public void doTest() throws Exception { SerializerGroup g = SerializerGroup.create() .append(JsonSerializer.class, XmlSerializer.class, HtmlSerializer.class) .sq() .pojoSwaps(MyJsonSwap.class, MyXmlSwap.class, MyOtherSwap.class) .build(); MyPojo myPojo = new MyPojo(); String json = g.getWriterSerializer("text/json").serialize(myPojo); assertEquals("'It\\'s JSON!'", json); String xml = g.getWriterSerializer("text/xml").serialize(myPojo); assertEquals("<string>It's XML!</string>", xml); String html = g.getWriterSerializer("text/html").serialize(myPojo); assertEquals("<string>It's something else!</string>", html); } }

When multiple swaps match the same media type, a best-match algorithm is applied to find the correct swap to use.

In later sections we describe how annotations can be used to shorten this syntax:

@Swaps({MyJsonSwap.class,MyXmlSwap.class,MyOtherSwap.class}) public static class MyPojo {} @Swap(mediaTypes="*/json") public static class MyJsonSwap extends PojoSwap<MyPojo,String> {...} @Swap(mediaTypes="*/xml") public static class MyXmlSwap extends PojoSwap<MyPojo,String> {...} @Swap(mediaTypes="*/*") public static class MyOtherSwap extends PojoSwap<MyPojo,String> {...}

2.10.3 - One-way PojoSwaps

In the previous sections, we defined two-way swaps, meaning swaps where the original objects could be reconstructing during parsing.
However, there are certain kinds of POJOs that we may want to support for serializing, but that are not possible to reconstruct during parsing.
For these, we can use one-way object swaps.

A one-way POJO swap is simply an object transform that only implements the swap() method.
The unswap() method is simply left unimplemented.

An example of a one-way swaps would be one that allows Iterators to be serialized as JSON arrays.
It can make sense to be able to render Iterators as arrays, but in general it's not possible to reconstruct an Iterator during parsing.

public class IteratorSwap extends PojoSwap<Iterator,List> { @Override /* PojoSwap */ public List swap(Iterator o) { List l = new LinkedList(); while (o.hasNext()) l.add(o.next()); return l; } }

Here is an example of our one-way swap being used.
Note that trying to parse the original object will cause a ParseException to be thrown.

// Create a JSON serializer that can serialize Iterators. WriterSerializer s = JsonSerializer.create().simple().pojoSwaps(IteratorSwap.class).build(); // Construct an iterator we want to serialize. Iterator i = new ObjectList(1,2,3).iterator(); // Serialize our Iterator String json = s.serialize(i); // Produces "[1,2,3]" // Try to parse it. ReaderParser p = JsonParser.create().pojoSwaps(IteratorSwap.class).build(); i = p.parse(s, Iterator.class); // Throws ParseException!!!

2.10.4 - @Swap Annotation

@Swap can be used to associate a swap class using an annotation.
This is often cleaner than using the builder pojoSwaps() method since you can keep your swap class near your POJO class.

@Swap(MyPojoSwap.class) public class MyPojo { ... } // Sample swap for converting MyPojo classes to a simple string. public class MyPojoSwap extends PojoSwap<MyPojo,String> { @Override /* PojoSwap */ public String swap(BeanSession session, MyPojo o) { return o.toSomeSerializableForm(); } }

Multiple swaps can be associated with a POJO by using the @Swaps annotation:

@Swaps( { @Swap(MyJsonSwap.class), @Swap(MyXmlSwap.class), @Swap(MyOtherSwap.class) } ) public class MyPojo {}

Readers get serialized directly to the output of a serializer. Therefore it's possible to implement a swap that provides fully-customized output.

public class MyJsonSwap extends PojoSwap<MyPojo,Reader> { public MediaType[] forMediaTypes() { return MediaType.forStrings("*/json"); } public Reader swap(BeanSession session, MyPojo o) throws Exception { return new StringReader("{message:'Custom JSON!'}"); } }

The @Swap annotation can also be used on getters and setters as well to apply a swap to individual property values:

public class MyBean { private MyPojo myPojo; // Swap applied to bean property. @BeanProperty(swap=MyPojoSwap.class) public MyPojo getMyPojo() { return myPojo; } }

When applied to bean properties, the swap annotation need only be applied to either the getter, setter, or field.

The swap annotation can also be applied to the private field of a bean property, like so:

public class MyBean { @BeanProperty(swap=MyPojoSwap.class) private MyPojo myPojo; public MyPojo getMyPojo() { return myPojo; } public MyBean setMyPojo(MyPojo myPojo) { this.myPojo = myPojo; return this; } }

2.10.5 - Templated Swaps

The @Swap(template) annotation allows you to associate arbitrary contextual strings with swaps.
The primary purpose is for providing template names, such as for Apache FreeMarker, therefore the name 'template'.
However, the usage of the string is open-ended.

For example, you could pair a template string like so:

@Swap(impl=FreeMarkerSwap.class, template="MyPojo.div.ftl") public class MyPojo {}

The implementation of the FreeMarker swap would look something like this:

// Our templated swap class. public class FreeMarkerSwap extends PojoSwap<Object,Reader> { public MediaType[] forMediaTypes() { // Make sure this only applies to the HTML serializer. return MediaType.forStrings("*/html"); } public Reader swap(BeanSession session, Object o, String template) throws Exception { // Call some method that uses FreeMarker to convert 'o' to raw HTML using // the 'MyPojo.div.ftl' template. return getFreeMarkerReader(template, o); } }

2.10.6 - Swap Methods

Various methods can be defined on a class directly to affect how it gets serialized.
This can often be simpler than using PojoSwaps.

Objects serialized as Strings can be parsed back into their original objects by implementing one of the following methods on the class:

  • public static T fromString(String) method.
    Any of the following method names also work:
    • valueOf(String)
    • parse(String)
    • parseString(String)
    • forName(String)
    • forString(String)
  • public T(String) constructor.

Note that these methods cover conversion from several built-in Java types, meaning the parsers can automatically construct these objects from strings:

If you want to force a bean-like class to be serialized as a string, you can use the @BeanIgnore annotation on the class to force it to be serialized to a string using the toString() method.

Serializing to other intermediate objects can be accomplished by defining a swap method directly on the class:

  • public X swap(BeanSession) method, where X is any serializable object.

The BeanSession parameter allows you access to various information about the current serialization session.
For example, you could provide customized results based on the media type being produced (BeanSession.getMediaType()).

The following example shows how an HTML5 form template object can be created that gets serialized as a populated HTML5 Form bean.

import static org.apache.juneau.dto.html5.HtmlBuilder.*; /** * A simple HTML form template whose serialized form is an HTML5 Form object. */ public class FormTemplate { private String action; private int value1; private boolean value2; // Some constructor that initializes our fields. public FormTemplate(String action, int value1, boolean value2) { this.action = action; this.value1 = value1; this.value2 = value2; } // Special swap method that converts this template to a serializable bean public Form swap(BeanSession session) { return form(action, input("text").name("v1").value(value1), input("text").name("v2").value(value2) ); } }

Swapped objects can be converted back into their original form by the parsers by specifying one of the following methods:

  • public static T unswap(BeanSession, X) method where X is the swap class type.
  • public T(X) constructor where X is the swap class type.

The following shows how our form template class can be modified to allow the parsers to reconstruct our original object:

import static org.apache.juneau.dto.html5.HtmlBuilder.*; /** * A simple HTML form template whose serialized form is an HTML5 Form object. * This time with parsing support. */ @Bean(beanDictionary=HtmlBeanDictionary.class) public class FormTemplate { private String action; private int value1; private boolean value2; // Our 'unswap' constructor public FormTemplate(Form f) { this.action = f.getAttr("action"); this.value1 = f.getChild(Input.class, 0) .getAttr(int.class, "value"); this.value2 = f.getChild(Input.class, 1) .getAttr(boolean.class, "value"); } public FormTemplate(String action, int value1, boolean value2) { this.action = action; this.value1 = value1; this.value2 = value2; } public Form swap(BeanSession session) { return form(action, input("text").name("v1").value(value1), input("text").name("v2").value(value2) ); } }

2.10.7 - Surrogate Classes

Surrogate classes are very similar in concept to PojoSwaps except they're simpler to define.

For example, let's say we want to be able to serialize the following class, but it's not serializable for some reason (for example, there are no properties exposed):

// Not serializable because it's not a bean because it has no public properties. public class MyNonSerializableClass { protected String foo; }

This could be solved with the following PojoSwap.

// A serializable bean with 1 property. public class MySerializableSurrogate { public String foo; } // A PojoSwap that swaps out our non-serializable object with our serializable object. public class MySwap extends PojoSwap<MyNonSerializableClass,MySerializableSurrogate> { @Override /* PojoSwap */ public MySerializableSurrogate swap(MyNonSerializableClass o) { // Create some serializable class and manually copy the data into it. MySerializableSurrogate s = new MySerializableSurrogate(); s.foo = o.foo; return s; } }

However, the same can be accomplished by using a surrogate class that simply contains a constructor with the non-serializable class as an argument:

public class MySerializableSurrogate { public String foo; // Constructor takes in our non-serializable object! public MySerializableSurrogate(MyNonSerializableClass c) { this.foo = c.foo; } }

The surrogate class is registered in the same way as a PojoSwap:

// Create a JSON serializer that can serialize Iterators. WriterSerializer s = JsonSerializer.create().pojoSwaps(MySerializableSurrogate.class).build();

When the serializer encounters the non-serializable class, it will serialize an instance of the surrogate instead.

See Also:

2.10.8 - @BeanProperty Annotation

The @Bean annotation is used to tailor how beans are interpreted by the framework.

Bean property inclusion and ordering on a bean class can be done using the @Bean(properties) annotation.

// Address class with only street/city/state properties (in that order). // All other properties are ignored. @Bean(properties="street,city,state") public class Address { ... }

Bean properties can be excluded using the @Bean(excludeProperties) annotation.

// Address class with only street/city/state properties (in that order). // All other properties are ignored. @Bean(excludeProperties="city,state"}) public class Address { ... }

Bean properties can be sorted alphabetically using @Bean(sort)

// Address class with only street/city/state properties (in that order). // All other properties are ignored. @Bean(sort=true) public class MyBean { ... }

The @Bean(propertyNamer) annotation is used to provide customized naming of properties.

Property namers are used to transform bean property names from standard form to some other form.
For example, the PropertyNamerDLC will convert property names to dashed-lowercase, and these will be used as attribute names in JSON and element names in XML.

// Define a class with dashed-lowercase property names. @Bean(propertyNamer=PropertyNamerDashedLC.class) public class MyBean { ... }

The @Bean(interfaceClass) annotation is used to limit properties on beans to specific interface classes.
When specified, only the list of properties defined on the interface class will be used during serialization.
Additional properties on subclasses will be ignored.

// Parent class @Bean(interfaceClass=A.class) public abstract class A { public String f0 = "f0"; } // Child class public class A1 extends A { public String f1 = "f1"; } JsonSerializer s = SimpleJsonSerializer.DEFAULT; A1 a1 = new A1(); String r = s.serialize(a1); assertEquals("{f0:'f0'}", r); // Note f1 is not serialized.

Note that this annotation can be used on the parent class so that it filters to all child classes.
Or can be set individually on the child classes.

The @Bean(stopClass) annotation is another way to limit which properties are serialized (except from the opposite direction).
It's identical in purpose to the stop class specified by Introspector.getBeanInfo(Class, Class).
Any properties in the stop class or in its base classes will be ignored during analysis.

For example, in the following class hierarchy, instances of C3 will include property p3, but not p1 or p2.

public class C1 { public int getP1(); } public class C2 extends C1 { public int getP2(); } @Bean(stopClass=C2.class) public class C3 extends C2 { public int getP3(); }

The @Bean(propertyFilter) annotation and PropertyFilter class can be used to perform interception and inline handling of bean getter and setter calls.

// Register filter on bean class. @Bean(propertyFilter=AddressPropertyFilter.class) public class Address { public String getTaxInfo() {...} public void setTaxInfo(String s) {...} } // Property filter that strips out sensitive information in our bean. public class AddressPropertyFilter extends PropertyFilter { @Override /* PropertyFilter */ public Object readProperty(Object bean, String name, Object value) { if ("taxInfo".equals(name)) return "redacted"; return value; } @Override /* PropertyFilter */ public Object writeProperty(Object bean, String name, Object value) { AddressBook a = (Address)bean; if ("taxInfo".equals(name) && "redacted".equals(value)) return TaxInfoUtils.lookUpByName(a.getStreet(), a.getCity(), a.getState()); return value; } }

2.10.9 - @BeanProperty Annotation

The @BeanProperty annotation is used to tailor how individual bean properties are interpreted by the framework.

The @BeanProperty(name) annotation is used to override the name of the bean property.

public class MyBean { @BeanProperty(name="Bar") public String getFoo() {...} }

If the BeanContext.BEAN_beanFieldVisibility setting on the bean context excludes this field (e.g. the visibility is set to the default of PUBLIC, but the field is PROTECTED), this annotation can be used to force the field to be identified as a property.

public class MyBean { @BeanProperty protected String getFoo() {...} }

The bean property named "*" is the designated "dynamic property" which allows for "extra" bean properties not otherwise defined.
This is similar in concept to the Jackson @JsonGetterAll and @JsonSetterAll annotations, but generalized for all supported marshall languages.
The primary purpose is for backwards compatibility in parsing newer streams with addition information into older beans.

The following shows various ways of using dynamic bean properties.

// Option #1 - A simple public Map field. // The field name can be anything. public class BeanWithDynaField { @BeanProperty(name="*") public Map<String,Object> extraStuff = new LinkedHashMap<String,Object>(); } // Option #2 - Getters and setters. // Method names can be anything. // Getter must return a Map with String keys. // Setter must take in two arguments, a String and Object. public class BeanWithDynaMethods { @BeanProperty(name="*") public Map<String,Object> getMyExtraStuff() { ... } @BeanProperty(name="*") public void setAnExtraField(String name, Object value) { ... } } // Option #3 - Getter only. // Properties will be added through the getter. public class BeanWithDynaGetterOnly { @BeanProperty(name="*") public Map<String,Object> getMyExtraStuff() { ... } }

Similar rules apply for value types and swaps.
The property values optionally can be any serializable type or use swaps.

// A serializable type other than Object. public class BeanWithDynaFieldWithListValues { @BeanProperty(name="*") public Map<String,List<String>> getMyExtraStuff() { ... } } // A swapped value. public class BeanWithDynaFieldWithSwappedValues { @BeanProperty(name="*", swap=CalendarSwap.ISO8601DTZ.class) public Map<String,Calendar> getMyExtraStuff() { ... } }

The @BeanProperty(value) annotation is a synonym for @BeanProperty(name).
Use it in cases where you're only specifying a name so that you can shorten your annotation.

The following annotations are equivalent:

@BeanProperty(name="foo") @BeanProperty("foo")

The @BeanProperty(type) annotation is used to identify a specialized class type for a generalized property.
Normally the type is inferred through reflection of the field type or getter return type.
However, you'll want to specify this value if you're parsing beans where the bean property class is an interface or abstract class to identify the bean type to instantiate.
Otherwise, you may cause an InstantiationException when trying to set these fields.

This property must denote a concrete class with a no-arg constructor.

public class MyBean { // Identify concrete type as a HashMap. @BeanProperty(type=HashMap.class) public Map p1; }

The @BeanProperty(params) annotation is for bean properties of type map or collection.
It's used to identify the class types of the contents of the bean property object when the general parameter types are interfaces or abstract classes.

public class MyBean { // This is a HashMap<String,Integer>. @BeanProperty(type=HashMap.class, params={String.class,Integer.class}) public Map p1; }

The @BeanProperty(properties) annotation is used to limit which child properties are rendered by the serializers.
It can be used on any of the following bean property types:

  • Beans - Only render the specified properties of the bean.
  • Maps - Only render the specified entries in the map.
  • Bean/Map arrays - Same, but applied to each element in the array.
  • Bean/Map collections - Same, but applied to each element in the collection.

public class MyClass { // Only render 'f1' when serializing this bean property. @BeanProperty(properties={"f1"}) public MyChildClass x1 = new MyChildClass(); } public class MyChildClass { public int f1 = 1; public int f2 = 2; } // Renders "{x1:{f1:1}}" String json = JsonSerializer.DEFAULT.serialize(new MyClass());

The @BeanProperty(format) annotation specifies a String format for converting a bean property value to a formatted string.

// Serialize a float as a string with 2 decimal places. @BeanProperty(format="$%.2f") public float price;

2.10.10 - @BeanConstructor Annotation

The @BeanConstructor annotation is used to map constructor arguments to property names on bean with read-only properties.
Since method parameter names are lost during compilation, this annotation essentially redefines them so that they are available at runtime.

The definition of a read-only bean is a bean with properties with only getters, like shown below:

// Our read-only bean. public class Person { private final String name; private final int age; @BeanConstructor(properties="name,age"}) public Person(String name, int age) { this.name = name; this.age = age; } // Read only properties. // Getters, but no setters. public String getName() { return name; } public int getAge() { return age; } }

// Parsing into a read-only bean. String json = "{name:'John Smith',age:45}"; Person p = JsonParser.DEFAULT.parse(json); String name = p.getName(); // "John Smith" int age = p.getAge(); // 45

Beans can also be defined with a combination of read-only and read-write properties.

2.10.11 - @BeanIgnore Annotation

The @BeanIgnore annotation is used to ignore classes, fields, and methods from being interpreted as beans or bean components.

When applied to classes, objects will be converted to strings even though they look like beans.

// Not really a bean! Use toString() instead! @BeanIgnore public class MyBean {...}

When applied to fields and getters/setters, they will be ignored as bean properties.

public class MyBean { // Not a bean property! @BeanIgnore public String foo; // Not a bean property! @BeanIgnore public String getBar() {...} }

2.10.12 - @NameProperty Annotation

The @NameProperty annotation is used to identify a setter as a method for setting the name of a POJO as it's known by its parent object.

A commonly-used case is when you're parsing a JSON map containing beans where one of the bean properties is the key used in the map.

// JSON { id1: {name: 'John Smith', sex: 'M'}, id2: {name: 'Jane Doe', sex: 'F'} }

public class Person { @NameProperty public String id; // Value gets assigned from object key public String name; public char sex; }

2.10.13 - @ParentProperty Annotation

The @ParentProperty annotation is used to identify a setter as a method for adding a parent reference to a child object.

A commonly-used case is when you're parsing beans and a child bean has a reference to a parent bean.

public class AddressBook { public List<Person> people; } public class Person { @ParentProperty public AddressBook addressBook; // A reference to the containing address book. public String name; public char sex; }

Parsers will automatically set this field for you in the child beans.

2.10.14 - POJO Builders

Juneau parsers can use builders to instantiate POJOs.
This is useful in cases where you want to create beans with read-only properties.
Note that while it's possible to do this using the @BeanConstructor annotation, using builders can often be cleaner.

A typical builder usage is shown below:

MyBean b = MyBean.create().foo("foo").bar(123).build();

The code for such a builder is shown below:

public class MyBean { // Read-only properties. public final String foo; public final int bar; // Private constructor. private MyBean(MyBeanBuilder b) { this.foo = b.foo; this.bar = b.bar; } // Static method that creates a builder. public static MyBeanBuilder create() { return new MyBeanBuilder(); } // Builder class. public static class MyBeanBuilder { private String foo; private int bar; // Method that creates the bean. public MyBean build() { return new MyBean(this); } // Bean property setters. @BeanProperty public MyBeanBuilder foo(String foo) { this.foo = foo; return this; } @BeanProperty public MyBeanBuilder bar(int bar) { this.bar = bar; return this; } } }

The POJO class can be any type including beans.
Builders MUST be beans with one or more writable properties.
The bean properties themselves do not need to be readable (i.e. getters are optional).

Builders require two parts:

  1. A way to detect and instantiate a builder using reflection.
  2. A way to instantiate a POJO from a builder.

The first can be accomplished through any of the following:

  • A static create() method on the POJO class that returns a builder instance.

    public static MyBuilder create() {...}

  • A public constructor on the POJO class that takes in a single parameter that implements the Builder interface.
    The builder class must have a public no-arg constructor.

    public MyPojo(MyBuilder b) {...}

  • A @Builder annotation on the POJO class.
    The builder class must have a public no-arg constructor.

    @Builder(MyBuilder.class) public class MyPojo {...}

The second can be accomplished through any of the following:

  • The existence of a build() method on the builder class.

    public MyPojo build() {...}

  • The existence of a public constructor on the POJO class that takes in the builder instance.

    public MyPojo(MyBuilder b) {...}

See Also:

2.10.15 - BeanFilter Class

The BeanFilter class is the programmatic equivalent to the @Bean annotation.

In practice, it's usually simpler to use the @Bean and @BeanProperty annotations on your bean classes.
However, bean filters make it possible to accomplish the same when you can't add annotations to existing code.

Bean filters are defined through BeanFilterBuilders.

In the previous examples, we defined this bean annotation:

@Bean(properties="street,city,state") public class Address { ... }

The programmatic equivalent would be:

public class AddressFilter extends BeanFilterBuilder<Address> { // Must provide a no-arg constructor! public AddressFilter() { includeProperties("street,city,state"); // The properties we want exposed. } }

Bean filters are added to serializers and parsers using the following:

For example:

// Create a new JSON serializer and associate a bean filter with it. WriterSerializer s = JsonSerializer .create() .beanFilters(AddressFilter.class) .build();

Note that if you use the annotation, you do NOT need to set anything on the serializers/parsers.
The annotations will be detected and bean filters will automatically be created for them.

The BeanContextBuilder.beanFilters(Object...) method also allows you to pass in interfaces.
Any class that's not a subclass of BeanFilterBuilder get interpreted as bean interface classes.
These cause bean implementations of those interfaces to only expose the properties defined on the interface.

// An interface with the 3 properties we want serialized. public interface AddressInterface { public String getStreet(); public String getCity(); public String getState(); } // Our bean implementation. public class Address implements AddressInterface { public String getStreet() {...}; public String getCity() {...}; public String getState() {...}; public String getCountry() {...}; } // Create a new JSON serializer that only exposes street,city,state on Address bean. // The 'country' field will be ignored. WriterSerializer s = JsonSerializer .create() .beanFilters(AddressInterface.class) .build();

2.10.16 - Interface Filters

Occasionally, you may want to limit bean properties to only those defined on a parent class or interface.
This is accomplished through interface filters.

Interface filters are defined through the following:

For example, let's define the following interface and implementation:

// Interface public class MyInterface { public String getFoo(); } // Implementation public class MyInterfaceImpl implements MyInterface { public String getFoo() {...} public String getBar() {...} }

Suppose we only want to render the properties defined on our interface, not the implementation.
To do so, we can define the following bean filter:

// Define transform that limits properties to only those defined on MyClass public class MyInterfaceFilter extends BeanFilter<MyInterface> { public MyInterfaceFilter() { interfaceClass(MyInterface.class); } }

When serialized, the serialized bean will only include properties defined on the interface.

WriterSerializer s = JsonSerializer .create() .simple() .beanFilters(MyInterfaceFilter.class) .build(); MyInterface o = new MyInterfaceImpl(); // Prints "{foo:'foo'}" // bar is ignored because it's not on the interface String json = s.serialize(o);

The BeanContextBuilder.beanFilters(Object...) method will automatically interpret any non-BeanFilter classes passed in as meaning interface classes.
So in the previous example, the BeanFilter class could have been avoided altogether by just passing in MyInterface.class to the serializer, like so:

WriterSerializer s = JsonSerializer .create() .beanFilters(MyInterface.class) Shortcut! .build();

The annotation equivalent is Bean#interfaceClass().

@Bean(interfaceClass=MyInterface.class) public class MyInterfaceImpl implements MyInterface { public String getFoo() {...} public String getBar() {...} }

The annotation can be used in a couple of ways.

Using the annotation on an interface will be inherited by all children.

@Bean(interfaceClass=MyInterface.class) public class MyInterface { public String getFoo(); }

The annotation can be used on parent classes as well.
Child beans will only serialize properties defined on the parent class.

@Bean(interfaceClass=MyAbstractClass.class) public abstract class MyAbstractClass { public String getFoo() {...}; }

2.10.17 - Stop Classes

Whereas interface filters limit properties defined on child classes, stop filters do the opposite and limit properties defined on parent classes.

Stop classes are defined through the following:

Stop classes are identical in purpose to the stop class specified by Introspector.getBeanInfo(Class, Class).
Any properties in the stop class or in its base classes will be ignored during serialization.

For example, in the following class hierarchy, instances of C3 will include property p3, but not p1 or p2.

public class C1 { public int getP1(); } public class C2 extends C1 { public int getP2(); } @Bean(stopClass=C2.class) public class C3 extends C2 { public int getP3(); } // Serializes property 'p3', but NOT 'p1' or 'p2'. String json = JsonSerializer.DEFAULT.serialize(new C3());

2.10.18 - Bypass Serialization using Readers and InputStreams

Juneau serializers treat instances of Readers and InputStreams special by simply serializing their contents directly to the output stream or writer.
This allows you to embed fully customized serializer output.

public class MyBean { // A bean property that produces raw JSON. public Reader f1 = new StringReader("{'foo':'bar'}"); } // Produces "{f1:{'foo':'bar'}}" String json = SimpleJsonSerializer.DEFAULT .toString(new MyBean());

Note that if you're serializing Readers and InputStreams, it's up to you to make sure you're producing valid output (in this case JSON).

A more typical scenario where this is useful is by using swaps to convert POJOs to Readers whose contents are determined via the BeanSession.getMediaType() method.
In the following example, we're customizing the JSON output for a particular bean type, but leaving all other renditions as-is:

@Swap(MyBeanSwapSometimes.class) public class MyBean {...} // A swap that produces specialized output for JSON, but default serialization for // all other media types. public class MyBeanSwapSometimes extends PojoSwap<MyBean,Object> { public Object swap(BeanSession session, MyPojo o) throws Exception { MediaType mt = session.getMediaType(); if (mt.hasSubType("json")) return new StringReader("{myPojo:'foobar'}"); // Custom JSON output return o; // Otherwise serialize it as a normal bean } }

  • Due to the nature of the RDF serializers, Readers and InputStreams are serialized as literals, not as RDF text. This is due to the fact that the RDF serializers use a DOM for serialization, so we don't have access to the underlying stream.

2.11 - Bean Names and Dictionaries

While parsing into beans, Juneau attempts to determine the class types of bean properties through reflection on the bean property getter or setter.
Often this is insufficient if the property type is an interface or abstract class that cannot be instantiated.
This is where bean names and dictionaries come into play.

Bean names and dictionaries are used for identifying class types when they cannot be inferred through reflection.

Bean classes are given names through the @Bean(typeName) annotation.
These names are then added to the serialized output as virtual "_type" properties (or element names in XML).

On the parsing side, these type names are resolved to classes through the use of bean dictionaries.

For example, if a bean property is of type Object, then the serializer will add "_type" attributes so that the class can be determined during parsing.

@Bean(typeName="foo") public class Foo { // A bean property where the object types cannot be inferred since it's an Object[]. @BeanProperty(beanDictionary={Bar.class,Baz.class}) public Object[] x = new Object[]{new Bar(), new Baz()}; } @Bean(typeName="bar") public class Bar {} @Bean(typeName="baz") public class Baz {}

When serialized as JSON, "_type" attributes would be added when needed to infer the type during parsing:

{ x: [ {_type:'bar'}, {_type:'baz'} ] }

Type names can be represented slightly differently in different languages.
For example, the dictionary name is used as element names when serialized to XML.
This allows the typeName annotation to be used as a shortcut for defining element names for beans.

When serialized as XML, the bean is rendered as:

<foo> <x> <bar/> <baz/> </x> </foo>

Bean dictionaries are registered through the following:

The bean dictionary setting can consist of any of the following types:

  • Any bean class that specifies a value for @Bean(typeName).
  • Any subclass of BeanDictionaryList containing a collection of bean classes with type name annotations.
  • Any subclass of BeanDictionaryMap containing a mapping of type names to classes without type name annotations.
  • Any array or collection of the objects above.

// Create a parser and tell it which classes to try to resolve. ReaderParser p = JsonParser .create() .beanDictionary(Foo.class, Bar.class) .build(); // Same, but use property. ReaderParser p = JsonParser .create() .addTo(BEAN_beanDictionary, Foo.class) .addTo(BEAN_beanDictionary, Bar.class) .build(); // Use the predefined HTML5 bean dictionary which is a BeanDictionaryList. ReaderParser p = HtmlParser .create() .beanDictionary(HtmlBeanDictionary.class) .build();

The "_type" property name can be overridden through the following:

When using the annotation, you'll typically want to define it on an interface class so that it can be inherited by all subclasses.

@Bean(typePropertyName="mytype", beanDictionary={MyClass1.class,MyClass2.class}) public interface MyInterface {...} @Bean(typeName="C1") public class MyClass1 implements MyInterface {...} @Bean(typeName="C2") public class MyClass2 implements MyInterface {...} MyInterface[] x = new MyInterface[]{ new MyClass1(), new MyClass2() }; // Produces "[{mytype:'C1',...},{mytype:'C2',...}]" String json = SimpleJsonSerializer.DEFAULT.serialize(x);

  • Type names do not need to be universally unique. However, they must be unique within a dictionary.
  • The following reserved words cannot be used as type names: object, array, number, boolean, null.
  • Serialized type names are DISABLED by default. They must be enabled on the serializer using the Serializer.SERIALIZER_addBeanTypes configuration property.

2.11.1 - Bean Subtypes

In addition to the bean type name support described above, simplified support is provided for bean subtypes.

Bean subtypes are similar in concept to bean type names, except for the following differences:

  • You specify the list of possible subclasses through an annotation on a parent bean class.
  • You do not need to register the subtype classes on the bean dictionary of the parser.

In the following example, the abstract class has two subclasses:

// Abstract superclass @Bean( beanDictionary={A1.class, A2.class} ) public abstract class A { public String f0 = "f0"; } // Subclass 1 @Bean(typeName="A1") public class A1 extends A { public String f1; } // Subclass 2 @Bean(typeName="A2") public class A2 extends A { public String f2; }

When serialized, the subtype is serialized as a virtual "_type" property:

JsonSerializer s = SimpleJsonSerializer.DEFAULT; A1 a1 = new A1(); a1.f1 = "f1"; String r = s.serialize(a1); assertEquals("{_type:'A1',f1:'f1',f0:'f0'}", r);

The following shows what happens when parsing back into the original object.

JsonParser p = JsonParser.DEFAULT; A a = p.parse(r, A.class); assertTrue(a instanceof A1);

2.12 - Virtual Beans

The BeanContext.BEAN_useInterfaceProxies setting (enabled by default) allows the Juneau parsers to parse content into virtual beans (bean interfaces without implementation classes).

For example, the following code creates an instance of the specified unimplemented interface:

// Our unimplemented interface public interface Address { String getStreet(); void setStreet(String x); String getCity(); void setCity(String x); StateEnum getState(); void setState(StateEnum x); int getZip(); void setZip(int zip); } // Our code Address address = JsonParser.DEFAULT.parse( "{street:'123 Main St', city:'Anywhere', state:'PR', zip:12345}", Address.class ); int zip = address.getZip(); address.setState(StateEnum.NY);

Getter and setter values can be any parsable values, even other virtual beans.

Under-the-covers, a virtual bean is simply a proxy interface on top of an existing BeanMap instance. From a programmatic point-of-view, they're indistinguishable from real beans, and can be manipulated and serialized like any other bean.

Virtual beans can also be created programmatically using the BeanContext class:

Address address = BeanContext.DEFAULT.createSession().newBean(Address.class);

2.13 - Non-Tree Models and Recursion Detection

The Juneau Serializer API is designed to be used against POJO tree structures.
It expects that there not be loops in the POJO model (e.g. children with references to parents, etc...).
If you try to serialize models with loops, you will usually cause a StackOverflowError to be thrown (if BeanTraverseContext.BEANTRAVERSE_maxDepth is not reached first).

If you still want to use the Juneau serializers on such models, Juneau provides the BeanTraverseContext.BEANTRAVERSE_detectRecursions setting.
It tells the serializer to look for instances of an object in the current branch of the tree and skip serialization when a duplicate is encountered.

For example, let's make a POJO model out of the following classes:

public class A { public B b; } public class B { public C c; } public class C { public A a; }

Now we create a model with a loop and serialize the results.

// Clone an existing serializer and set property for detecting recursions. JsonSerializer s = SimpleJsonSerializer.DEFAULT_READABLE.builder().detectRecursions(true).build(); // Create a recursive loop. A a = new A(); a.b = new B(); a.b.c = new C(); a.b.c.a = a; // Serialize to JSON. String json = s.serialize(a);

What we end up with is the following, which does not serialize the contents of the c field:

{ b: { c: { } } }

Without recursion detection enabled, this would cause a stack-overflow error.

Recursion detection introduces a performance penalty of around 20%.
For this reason the setting is disabled by default.

2.14 - Parsing into Generic Models

The Juneau parsers are not limited to parsing back into the original bean classes.
If the bean classes are not available on the parsing side, the parser can also be used to parse into a generic model consisting of Maps, Collections, and primitive objects.

You can parse into any Map type (e.g. HashMap, TreeMap), but using ObjectMap is recommended since it has many convenience methods for converting values to various types.
The same is true when parsing collections. You can use any Collection (e.g. HashSet, LinkedList) or array (e.g. Object[], String[], String[][]), but using ObjectList is recommended.

When the map or list type is not specified, or is the abstract Map, Collection, or List types, the parser will use ObjectMap and ObjectList by default.

For example, given the following JSON:

{ id: 1, name: 'John Smith', uri: 'http://sample/addressBook/person/1', addressBookUri: 'http://sample/addressBook', birthDate: '1946-08-12T00:00:00Z', addresses: [ { uri: 'http://sample/addressBook/address/1', personUri: 'http://sample/addressBook/person/1', id: 1, street: '100 Main Street', city: 'Anywhereville', state: 'NY', zip: 12345, isCurrent: true } ] }

We can parse this into a generic ObjectMap:

// Parse JSON into a generic POJO model. ObjectMap m = JsonParser.DEFAULT.parse(json, ObjectMap.class); // Convert it back to JSON. String json = SimpleJsonSerializer.DEFAULT_READABLE.serialize(m);

What we end up with is the exact same output.
Even the numbers and booleans are preserved because they are parsed into Number and Boolean objects when parsing into generic models.

{ id: 1, name: 'John Smith', uri: 'http://sample/addressBook/person/1', addressBookUri: 'http://sample/addressBook', birthDate: '1946-08-12T00:00:00Z', addresses: [ { uri: 'http://sample/addressBook/address/1', personUri: 'http://sample/addressBook/person/1', id: 1, street: '100 Main Street', city: 'Anywhereville', state: 'NY', zip: 12345, isCurrent: true } ] }

Once parsed into a generic model, various convenience methods are provided on the ObjectMap and ObjectList classes to retrieve values:

// Parse JSON into a generic POJO model. ObjectMap m = JsonParser.DEFAULT.parse(json, ObjectMap.class); // Get some simple values. String name = m.getString("name"); int id = m.getInt("id"); // Get a value convertable from a String. URI uri = m.get(URI.class, "uri"); // Get a value using a swap. CalendarSwap swap = new CalendarSwap.ISO8601DTZ(); Calendar birthDate = m.get(swap, "birthDate"); // Get the addresses. ObjectList addresses = m.getObjectList("addresses"); // Get the first address and convert it to a bean. Address address = addresses.get(Address.class, 0);

As a general rule, parsing into beans is often more efficient than parsing into generic models.
And working with beans is often less error prone than working with generic models.

2.15 - Reading Continuous Streams

The following parsers can be configured to read continuous streams of objects from the same input stream:

The JsonParser and UonParser classes can read continuous streams by using the PARSER_unbuffered setting.
This prevents the parsers from using an internal buffer that would read past the end of the currently parsed POJO.

Examples:

// If you're calling parse on the same input multiple times, use a session instead of the parser directly. ReaderParserSession p = JsonParser.create().unbuffered().build().createSession(); Object x; Reader r; r = new StringReader("{foo:'bar'}{baz:'qux'}"); x = p.parse(r, ObjectMap.class); // {foo:'bar'} x = p.parse(r, ObjectMap.class); // {baz:'qux'} r = reader("[123][456]"); x = p.parse(r, int[].class); // [123] x = p.parse(r, int[].class); // [456]

Note that this isn't perfect in all cases since you can't combine two JSON numbers into a single reader (e.g. "123" + "456" = "123456").

For obvious reasons, do not use the following properties when reading continuous streams:

The MsgPackParser class doesn't use any internal buffering to begin with, so it can be used with continuous streams without any special properties.

2.16 - URIs

Juneau serializers have sophisticated support for transforming relative URIs to absolute form.

The classes and settings that control the behavior are:

The following example shows a bean containing URIs of various forms and how they end up serialized.

// Our bean with properties containing various kinds of URIs. public class TestURIs { public URI f1a = URI.create("http://www.apache.org/f1a"), f1b = URI.create("/f1b"), f1c = URI.create("/f1c/x/y"), f1d = URI.create("f1d"), f1e = URI.create("f1e/x/y"), f1f = URI.create(""), f2a = URI.create("context:/f2a/x"), f2b = URI.create("context:/f2b"), f2c = URI.create("context:/"), f2d = URI.create("context:/.."), f3a = URI.create("servlet:/f3a/x"), f3b = URI.create("servlet:/f3b"), f3c = URI.create("servlet:/"), f3d = URI.create("servlet:/.."), f4a = URI.create("request:/f4a/x"), f4b = URI.create("request:/f4b"), f4c = URI.create("request:/"), f4d = URI.create("request:/..");; } // Create a serializer. WriterSerializer s = JsonSerializer create() .simple() .uriContext("{authority:'http://foo.com:123',contextRoot:'/myContext',servletPath:'/myServlet',pathInfo:'/myPath'}") .uriResolution(ABSOLUTE) .uriRelativity(RESOURCE) .build(); // Produces: // { // f1a:'http://www.apache.org/f1a', // f1b:'http://foo.com:123/f1b', // f1c:'http://foo.com:123/f1c/x/y', // f1d:'http://foo.com:123/myContext/myServlet/f1d', // f1e:'http://foo.com:123/myContext/myServlet/f1e/x/y', // f1f:'http://foo.com:123/myContext/myServlet', // f2a:'http://foo.com:123/myContext/f2a/x', // f2b:'http://foo.com:123/myContext/f2b', // f2c:'http://foo.com:123/myContext', // f2d:'http://foo.com:123' // f3a:'http://foo.com:123/myContext/myServlet/f3a/x', // f3b:'http://foo.com:123/myContext/myServlet/f3b', // f3c:'http://foo.com:123/myContext/myServlet', // f3d:'http://foo.com:123/myContext', // f4a:'http://foo.com:123/myContext/myServlet/myPath/f4a/x', // f4b:'http://foo.com:123/myContext/myServlet/myPath/f4b', // f4c:'http://foo.com:123/myContext/myServlet/myPath', // f4d:'http://foo.com:123/myContext/myServlet' // } String json = s.serialize(new TestURIs());

URI resolution is controlled by the following settings:

Juneau automatically interprets any URL and URI objects as URIs and will resolve them accordingly.
The @URI annotation can be used to extend that to other bean properties and class types so that they also get interpreted as URIs.
For example:

// Applied to a class whose toString() method returns a URI. @URI public class MyURI { @Override /* Object */ public String toString() { return "http://localhost:9080/foo/bar"; } } // Applied to bean properties public class MyBean { @URI public String beanUri; @URI public String getParentUri() { ... } }

2.17 - Comparison with Jackson

Juneau was developed independently from Jackson, but shares many of the same features and capabilities. Whereas Jackson was created to work primarily with JSON, Juneau was created to work for multiple languages. Therefore, the terminology and annotations in Juneau are similar, but language-agnostic.

The following charts describe equivalent features between the two libraries:

Annotations
JacksonJuneau
@JsonGetter
@JsonSetter
@BeanProperty
@JsonAnyGetter
@JsonAnySetter
@BeanProperty(name="*")
@JsonIgnore
@JsonIgnoreType
@BeanIgnore
@JsonIgnoreProperties({...}) @Bean(excludeProperties="...")
@JsonAutoDetect(fieldVisibility=...) No equivalent annotation, but can be controlled via:
BeanContext.BEAN_beanFieldVisibility
BeanContext.BEAN_beanMethodVisibility
Future annotation support planned.
@JsonCreator
@JsonProperty
@BeanConstructor
@JacksonInject No equivalent.
Future support planned.
@JsonSerialize
@JsonDeserialize
Juneau uses swaps to convert non-serializable object to serializable forms:
@Swap
@JsonInclude No equivalent annotation, but can be controlled via various settings:
BeanContext
Serializer
Future annotation support planned.
@JsonPropertyOrder @Bean(properties="...")
@Bean(sort=x)
@JsonValue
@JsonRawValue
Can be replicated using swaps with Reader swapped values.

2.18 - POJO Categories

The following chart shows POJOs categorized into groups and whether they can be serialized or parsed:

General POJO serialization/parsing support
GroupDescriptionExamplesCan
serialize?
Can
parse?
1 Java primitives and primitive objects
  • String
  • Integer
  • Float
  • Boolean
yes yes
2 Java Collections Framework objects and Java arrays      
2a With standard keys/values
Map keys are group [1, 4a, 6a] objects.
Map, Collection, and array values are group [1, 2, 3ac, 4a, 6a] objects.
  • HashSet<String,Integer>
  • TreeMap<Integer,Bean>
  • List<int[][]>
  • Bean[]
yes yes
2b With non-standard keys/values
Map keys are group [2, 3, 4b, 5, 6b, 7] objects.
Map, Collection, and array values are group [3b, 4b, 5, 6b, 7] objects.
  • HashSet<Bean,Integer>
  • TreeMap<Integer,Reader>
yes no
3 Java Beans      
3a With standard properties
These are beans that have one or more properties defined by public getter or public fields.
Properties can also be defined as final read-only fields and passed in as constructor args.
Property values are group [1, 2, 3ac, 4a, 6a] objects.
  yes yes
3b With non-standard properties or not true beans
These include true beans that have one or more properties defined by getter and setter methods or properties, but property types include group [3b, 4b, 5, 6b, 7] objects.
This also includes classes that look like beans but aren't true beans. For example, classes that have getters but not setters, or classes without no-arg constructors.
  yes no
3c Virtual beans
These are unimplemented bean interfaces with properties of type [1, 2, 3ac, 4a, 6a] objects.
Parsers will automatically create interface proxies on top of BeanMap instances.
  yes yes
3d Read-only beans without setters
The same as 3a, but without property setters or constructor args.
  yes no
4 Swapped objects
These are objects that are not directly serializable, but have PojoSwaps associated with them. The purpose of a POJO swap is to convert an object to another object that is easier to serialize and parse. For example, the DateSwap.ISO8601DT class can be used to serialize Date objects to ISO8601 strings, and parse them back into Date objects.
     
4a 2-way swapped to group [1, 2a, 3ac] objects
For example, a swap that converts a Date to a String.
  • java.util.Date
  • java.util.GregorianCalendar
yes yes
4b 1-way swapped to group [1, 2, 3] objects
For example, a swap that converts an Iterator to a List. This would be one way, since you cannot reconstruct an Iterator.
  • java.util.Iterator
yes no
5 Readers and InputStreams
Contents are serialized directly to the output stream or writer.
Typically used for low-level language-specific replacement of POJOs using per-Media-Type POJO swaps.
  • FileInputStream
  • StringReader
yes no
6 Non-serializable objects with standard methods for converting to a serializable form
     
6a Classes with a method that converts it to a serializable form:
  • public X swap(BeanSession); where X is in groups [1, 2a, 3ac].
  • public String toString(); where the string is any meaningful data.
And a method that converts it back into the original object:
  • public static T fromString(String);
  • public static T valueOf(String);
  • public static T parse(String);
  • public static T parseString(String);
  • public static T forName(String);
  • public static T forString(String);
  • public T(X); where X is in groups [1, 2a, 3ac].
  • public static T unswap(BeanSession,X); where X is in groups [1, 2a, 3ac].
  • java.lang.Class
  • java.sql.Time
  • java.sql.Timestamp
  • java.text.MessageFormat
  • java.text.NumberFormat
  • java.util.Date
  • java.util.UUID
  • java.util.logging.Level
  • javax.xml.bind.DatatypeConverter
yes yes
6b Classes that only have a method to convert to a serializable form:
  • public X swap(BeanSession); where X is in groups [1, 2, 3].
  • public String toString(); where the string is any meaningful data.
  yes no
7 All other objects
Anything that doesn't fall into one of the groups above are simply converted to Strings using the toString() method.
  yes no
  • Serializers are designed to work on tree-shaped POJO models. These are models where there are no referential loops (e.g. leaves with references to nodes, or nodes in one branch referencing nodes in another branch). There is a serializer setting detectRecursions to look for and handle these kinds of loops (by setting these references to null), but it is not enabled by default since it introduces a moderate performance penalty.
POJOs convertible to/from Strings

A separate category exists for POJOs that can be converted to and from Strings. These are used in places such as:

  • Serializing of POJOs to Strings in the REST client API when no serializers are registered.
  • Parsing of POJOs from Strings in the REST server API for "text/plain" requests where "text/plain" is not already mapped to an existing serializer.

As a general rule, all POJOs are converted to Strings using the toString() method.
However, there is one exception:

POJOs are convertible from Strings using any of the following (matched in the specified order):

  • Any any of the following public static non-deprecated methods:
    • create(String)
    • fromString(String)
    • fromValue(String)
    • valueOf(String)
    • parse(String)
    • parseString(String)
    • forName(String)
    • forString(String)
  • Has a public constructor that takes in a String.

Exceptions exist for the following classes:

POJOs convertible to/from other types

POJOs are also converted to various other types in places such as the Open-API serializers and parsers.
In this section, the type being converted to will be referred to as X.

POJOs are considered convertible from X if it has any of the following (matched in the specified order):

  • Any any of the following public static non-deprecated methods:
    • create(X)
    • from*(X)
  • Has a public constructor that takes in an X.
  • The X class has a public non-static no-arg non-deprecated method called to*().

POJOs are considered convertible from X if any of the reverse of above are true.

2.19 - JSON Details

Juneau supports converting arbitrary POJOs to and from JSON using ultra-efficient serializers and parsers.
The JSON serializer converts POJOs directly to JSON without the need for intermediate DOM objects using a highly-efficient state machine.
Likewise, the JSON parser creates POJOs directly from JSON without the need for intermediate DOM objects.

The following example shows JSON for a typical bean:

Sample Beans

public class Person { // Bean properties public String name; @Swap(CalendarSwap.ISO8601DTZ.class) public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } public class Address { // Bean properties public String street, city; public StateEnum state; public int zip; public boolean isCurrent; // Getters/setters omitted }

Sample Code

Person p = new Person() .name("John Smith") .birthDate("1946-08-12T00:00:00Z") .addresses( new Address() .street("100 Main Street") .city("Anywhereville") .state(NY) .zip(12345) .isCurrent(true); );

Normal JSON

{ "name": "John Smith", "birthDate": "1946-08-12T00:00:00Z", "addresses": [ { "street": "100 Main Street", "city": "Anywhereville", "state": "NY", "zip": 12345, "isCurrent": true } ] }

Simplified JSON

{ name: 'John Smith', birthDate: '1946-08-12T00:00:00Z', addresses: [ { street: '100 Main Street', city: 'Anywhereville', state: 'NY', zip: 12345, isCurrent: true } ] }

2.19.1 - JSON Methodology

The JSON data type produced depends on the Java object type being serialized.

  • Primitives and primitive objects are converted to JSON primitives.
  • Beans and Maps are converted to JSON objects.
  • Collections and arrays are converted to JSON arrays.
  • Anything else is converted to JSON strings.
Data type conversions:
POJO type JSON type Example Serialized form
String String serialize("foobar"); 'foobar'
Number Number serialize(123); 123
Boolean Boolean serialize(true); true
Null Null serialize(null); null
Beans with properties of any type on this list Object serialize(new MyBean()); {p1:'val1',p2:true}
Maps with values of any type on this list Object serialize(new TreeMap()); {key1:'val1',key2:true}
Collections and arrays of any type on this list Array serialize(new Object[]{1,"foo",true}); [1,'foo',true]

In addition, swaps can be used to convert non-serializable POJOs into serializable forms, such as converting Calendar object to ISO8601 strings, or byte[] arrays to Base-64 encoded strings.

2.19.2 - JSON Serializers

The JsonSerializer class is used to serialize POJOs into JSON.

The JSON serializer provides the following settings:

The following pre-configured serializers are provided for convenience:

2.19.3 - Simplified JSON

The SimpleJsonSerializer class can be used to serialized POJOs into Simplified JSON notation.

Simplified JSON is identical to JSON except for the following:

  • JSON attributes are only quoted when necessary.
  • Uses single-quotes for quoting.
Examples:

// Some free-form JSON. ObjectMap m = new ObjectMap() .append("foo", "x1") .append("_bar", "x2") .append(" baz ", "x3") .append("123", "x4") .append("return", "x5"); .append("", "x6");

// Serialized to standard JSON { "foo": "x1", "_bar": "x2", " baz ": "x3", "123": "x4", "return": "x5", "": "x6" }

// Serialized to simplified JSON { foo: 'x1', _bar: 'x2', ' baz ': 'x3', // Quoted due to embedded spaces. '123': 'x4', // Quoted to prevent confusion with number. 'return': 'x5', // Quoted because it's a keyword. '': 'x6' // Quoted because it's an empty string. }

The advantage to simplified JSON is you can represent it in a Java String in minimal form with minimal escaping.
This is particularly useful in cases such as unit testing where you can easily validate POJOs by simplifying them to Simplified JSON and do a simple string comparison.

WriterSerializer ws = SimpleJsonSerializer.DEFAULT; assertEquals("{foo:'bar',baz:123}", ws.toString(myPojo));

See Also:

2.19.4 - JSON Parsers

The JsonParser class is used to parse JSON into POJOs.

The JSON parser provides the following settings:

The following pre-configured parsers are provided for convenience:

The JSON parser supports ALL valid JSON, including:

  • Javascript comments.
  • Single or double quoted values.
  • Quoted (strict) or unquoted (non-strict) attributes.
  • JSON fragments (such as string, numeric, or boolean primitive values).
  • Concatenated strings.

2.19.5 - @Json Annotation

The @Json annotation is used to override the behavior of JsonSerializer on individual bean classes or properties.

The annotation can be applied to beans as well as other objects serialized to other types (e.g. strings).

The @Json(wrapperAttr) annotation can be used to wrap beans inside a JSON object with a specified attribute name.

Example:

@Json(wrapperAttr="personBean") public class Person { public String name = "John Smith"; }

The following shows the JSON representation with and without the annotation present:

Without annotation With annotation
{ name: 'John Smith' } { personBean: { name: 'John Smith' } }

2.19.6 - JSON-Schema Support

Juneau provides the JsonSchemaSerializer class for generating JSON-Schema documents that describe the output generated by the JsonSerializer class.
This class shares the same properties as JsonSerializer.
For convenience the JsonSerializer.getSchemaSerializer() method has been added for creating instances of schema serializers from the regular serializer instance.

Sample Beans

public class Person { // Bean properties public String name; public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } public class Address { // Bean properties public String street, city; public StateEnum state; public int zip; public boolean isCurrent; // Getters/setters omitted }

The code for creating our POJO model and generating JSON-Schema is shown below:

// Get the one of the default schema serializers. JsonSchemaSerializer s = JsonSchemaSerializer.DEFAULT_SIMPLE_READABLE; // Get the JSON Schema for the POJO. String jsonSchema = s.serialize(new Person()); // This also works. jsonSchema = s.serialize(Person.class);

JSON Schema

{ type: 'object', description: 'org.apache.juneau.sample.Person', properties: { name: { type: 'string', description: 'java.lang.String' }, birthDate: { type: 'string', description: 'java.util.Calendar' }, addresses: { type: 'array', description: 'java.util.LinkedList<org.apache.juneau.sample.Address>', items: { type: 'object', description: 'org.apache.juneau.sample.Address', properties: { street: { type: 'string', description: 'java.lang.String' }, city: { type: 'string', description: 'java.lang.String' }, state: { type: 'string', description: 'java.lang.String' }, zip: { type: 'number', description: 'int' }, isCurrent: { type: 'boolean', description: 'boolean' } } } } } }

2.20 - XML Details

Juneau supports converting arbitrary POJOs to and from XML using ultra-efficient serializers and parsers.
The XML serializer converts POJOs directly to XML without the need for intermediate DOM objects.
Likewise, the XML parser uses a STaX parser and creates POJOs directly without intermediate DOM objects.

Unlike frameworks such as JAXB, Juneau does not require POJO classes to be annotated to produce and consume XML.
However, several XML annotations are provided for handling namespaces and fine-tuning the format of the XML produced.

The following example shows XML for a typical bean:

Sample Beans

@Bean(typeName="person") public class Person { // Bean properties public String name; @Swap(CalendarSwap.ISO8601DTZ.class) public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } @Bean(typeName="address") public class Address { // Bean properties public String street, city; public StateEnum state; public int zip; public boolean isCurrent; // Getters/setters omitted }

Sample Code

Person p = new Person() .name("John Smith") .birthDate("1946-08-12T00:00:00Z") .addresses( new Address() .street("100 Main Street") .city("Anywhereville") .state(NY) .zip(12345) .isCurrent(true); );

Normal XML:

<person> <name>John Smith</name> <birthDate>1946-08-12T04:00:00Z</birthDate> <addresses> <address> <street>100 Main Street</street> <city>Anywhereville</city> <state>NY</state> <zip>12345</zip> <isCurrent>true</isCurrent> </address> </addresses> </person>


Juneau produces JSON-equivalent XML, meaning any valid JSON document can be losslessly converted into an XML equivalent.
In fact, all of the Juneau serializers and parsers are built upon this JSON-equivalence.

2.20.1 - XML Methodology

The following examples show how different data types are represented in XML. They mirror how the data structures are represented in JSON.

Simple types

The representation of loose (not a direct bean property value) simple types are shown below:

Data type JSON example XML
string 'foo' <string>foo</string>
boolean true <boolean>true</boolean>
integer 123 <number>123</number>
float 1.23 <number>1.23</number>
null null <null/>
Maps

Loose maps and beans use the element <object> for encapsulation.

_type attributes are added to bean properties or map entries if the type cannot be inferred through reflection (e.g. an Object or superclass/interface value type).

Data type JSON example XML
Map<String,String> { k1: 'v1' k2: null } <object> <k1>v1</k1> <k2 _type='null'/> </object>
Map<String,Number> { k1: 123, k2: 1.23, k3: null } <object> <k1>123</k1> <k2>1.23</k2> <k3 _type='null'/> </object>
Map<String,Object> { k1: 'v1' k2: 123, k3: 1.23, k4: true, k5: null } <object> <k1>v1</k1> <k2 _type='number'>123</k2> <k3 _type='number'>1.23</k3> <k4 _type='boolean'>true</k4> <k5 _type='null'/> </object>
Arrays

Loose collections and arrays use the element <array> for encapsulation.

Data type JSON example XML
String[] [ 'foo' null ] <array> <string>foo</string> <null/> </array>
Number[] [ 123, 1.23, null ] <array> <number>123</number> <number>1.23</number> <null/> </array>
Object[] [ 'foo', 123, 1.23, true, null ] <array> <string>foo</string> <number>123</number> <number>1.23</number> <boolean>true</boolean> <null/> </array>
String[][] [ ['foo', null], null, ] <array> <array> <string>foo</string> <null/> </array> <null/> </array>
int[] [ 123 ] <array> <number>123</number> </array>
boolean[] [ true ] <array> <boolean>true</boolean> </array>
List<String> [ 'foo' null ] <array> <string>foo</string> <null/> </array>
List<Number> [ 123, 1.23, null ] <array> <number>123</number> <number>1.23</number> <null/> </array>
List<Object> [ 'foo', 123, 1.23, true, null ] <array> <string>foo</string> <number>123</number> <number>1.23</number> <boolean>true</boolean> <null/> </array>
Beans
Data type JSON example XML
class MyBean { public String a; public int b; public Object c; // String value public Object d; // Integer value public MyBean2 e; public String[] f; public int[] g; } class MyBean2 { String h; } { a: 'foo', b: 123, c: 'bar', d: 456, e: { h: 'baz' } f: ['qux'] g: [789] } <object> <a>foo</a> <b>123</b> <c>bar</c> <d _type='number'>456</d> <e> <h>baz</h> </e> <f> <string>qux</string> </f> <g> <number>789</number> </g> </object>
Beans with Map properties
Data type JSON example XML
class MyBean { public Map<String,String> a; public Map<String,Number> b; public Map<String,Object> c; } { a: { k1: 'foo' }, b: { k2: 123 }, c: { k3: 'bar', k4: 456, k5: true, k6: null } } <object> <a> <k1>foo</k1> </a> <b> <k2>123</k2> </b> <c> <k3>bar</k3> <k4 _type='number'>456</k4> <k5 _type='boolean'>true</k5> <k6 _type='null'/> </c> </object>

2.20.2 - XML Serializers

The XmlSerializer class is used to serialize POJOs into XML.

The XmlDocSerializer class is the same, but serializes a <?xml?> header at the top of the file.

The XML serializers provide the following settings:

The following pre-configured serializers are provided for convenience:

2.20.3 - XML Parsers

The XmlParser class is used to parse XML into POJOs.

The XML parser provides the following settings:

The following pre-configured parsers are provided for convenience:

2.20.4 - @Bean(typeName) Annotation

The @Bean(typeName) annotation can be used to override the Juneau default name on bean elements. Types names serve two distinct purposes:

  1. To override the element name.
  2. To serve as a class identifier so that the bean class can be inferred during parsing if it cannot automatically be inferred through reflection.
Example
Data type JSON example Without annotation With annotation
@Bean(typeName="X") class MyBean { public String a; public int b; } { a: 'foo', b: 123 } <object> <a>foo</id> <b>123</name> </object> <X> <a>foo</id> <b>123</name> </X>

On bean properties, a _type attribute will be added if a type name is present and the bean class cannot be inferred through reflection.

In the following example, a type attribute is used on property 'b' but not property 'a' since 'b' is of type Object and therefore the bean class cannot be inferred.

Example
Java Without annotation With annotation
class MyBean { public BeanX a = new BeanX(); public Object b = new BeanX(); } @Bean(typeName="X") class BeanX { public String fx = "foo"; } <object> <a> <fx>foo</fx> </a> <b> <fx>foo</fx> </b> </object> <object> <a> <fx>foo</fx> </a> <b _type='X'> <fx>foo</fx> </b> </object>
  • string, number, boolean, object, array, and null are reserved keywords that cannot be used as type names.

Beans with type names are often used in conjunction with the @Bean(beanDictionary) and @BeanProperty(beanDictionary) annotations so that the beans can be resolved at parse time.
These annotations are not necessary during serialization, but are needed during parsing in order to resolve the bean types.

The following examples show how type names are used under various circumstances.

Pay special attention to when _type attributes are and are not used.

Examples
Java XML
@Bean(beanDictionary={BeanX.class}) class BeanWithArrayPropertiesWithTypeNames { public BeanX[] b1 = new BeanX[]{ new BeanX() }; public Object[] b2 = new BeanX[]{ new BeanX() }; public Object[] b3 = new Object[]{ new BeanX() }; } <object> <b1> <X> <fx>foo</fx> </X> </b1> <b2> <X> <fx>foo</fx> </X> </b2> <b3> <X> <fx>foo</fx> </X> </b3> </object>
@Bean(beanDictionary={BeanX.class}) class BeanWith2dArrayPropertiesWithTypeNames { public BeanX[][] b1 = new BeanX[][]{{ new BeanX() }}; public Object[][] b2 = new BeanX[][]{{ new BeanX() }}; public Object[][] b3 = new Object[][]{{ new BeanX() }}; } <object> <b1> <array> <X> <fx>foo</fx> </X> </array> </b1> <b2> <array> <X> <fx>foo</fx> </X> </array> </b2> <b3> <array> <X> <fx>foo</fx> </X> </array> </b3> </object>
@Bean(beanDictionary={BeanX.class}) class BeanWithMapPropertiesWithTypeNames { public Map<String,BeanX> b1 = new HashMap<>() {{ put("k1", new BeanX()); }}; public Map<String,Object> b2 = new HashMap<>() {{ put("k2", new BeanX()); }} } <object> <b1> <k1> <fx>foo</fx> </k1> </b1> <b2> <k2 _type='X'> <fx>foo</fx> </k2> </b2> </object>

Bean type names are also used for resolution when abstract fields are used.
The following examples show how they are used in a variety of circumstances.

Java XML
@Bean(beanDictionary={A.class}) class BeanWithAbstractFields { public A a = new A(); public IA ia = new A(); public AA aa = new A(); public Object o = new A(); } interface IA {} abstract class AA implements IA {} @Bean(typeName="A") class A extends AA { public String fa = "foo"; } <object> <a> <fa>foo</fa> </a> <ia _type='A'> <fa>foo</fa> </ia> <aa _type='A'> <fa>foo</fa> </aa> <o _type='A'> <fa>foo</fa> </o> </object>
@Bean(beanDictionary={A.class}) class BeanWithAbstractArrayFields { public A[] a = new A[]{new A()}; public IA[] ia1 = new A[]{new A()}; public IA[] ia2 = new IA[]{new A()}; public AA[] aa1 = new A[]{new A()}; public AA[] aa2 = new AA[]{new A()}; public Object[] o1 = new A[]{new A()}; public Object[] o2 = new Object[]{new A()}; } <object> <a> <A> <fa>foo</fa> </A> </a> <ia1> <A> <fa>foo</fa> </A> </ia1> <ia2> <A> <fa>foo</fa> </A> </ia2> <aa1> <A> <fa>foo</fa> </A> </aa1> <aa2> <A> <fa>foo</fa> </A> </aa2> <o1> <A> <fa>foo</fa> </A> </o1> <o2> <A> <fa>foo</fa> </A> </o2> </object>
@Bean(beanDictionary={A.class}) class BeanWithAbstractMapFields { public Map<String,A> a = new HashMap<>() {{ put("k1", new A()); }}; public Map<String,AA> b = new HashMap<>() {{ put("k2", new A()); }}; public Map<String,Object> c = new HashMap<>() {{ put("k3", new A()); }}; } <object> <a> <k1> <fa>foo</fa> </k1> </a> <b> <k2 _type='A'> <fa>foo</fa> </k2> </b> <c> <k3 _type='A'> <fa>foo</fa> </k3> </c> </object>
@Bean(beanDictionary={A.class}) class BeanWithAbstractMapArrayFields { public Map<String,A[]> a = new LinkedHashMap<>() {{ put("a1", new A[]{new A()}); }}; public Map<String,IA[]> ia = new LinkedHashMap<>() {{ put("ia1", new A[]{new A()}); put("ia2", new IA[]{new A()}); }}; public Map<String,AA[]> aa = new LinkedHashMap<>() {{ put("aa1", new A[]{new A()}); put("aa2", new AA[]{new A()}); }}; public Map<String,Object[]> o = newLinkedHashMap<>() {{ put("o1", new A[]{new A()}); put("o2", new AA[]{new A()}); }}; } <object> <a> <a1> <A> <fa>foo</fa> </A> </a1> </a> <ia> <ia1> <A> <fa>foo</fa> </A> </ia1> <ia2> <A> <fa>foo</fa> </A> </ia2> </ia> <aa> <aa1> <A> <fa>foo</fa> </A> </aa1> <aa2> <A> <fa>foo</fa> </A> </aa2> </aa> <o> <o1> <A> <fa>foo</fa> </A> </o1> <o2> <A> <fa>foo</fa> </A> </o2> </o> </object>

On a side note, characters that cannot be represented in XML 1.0 are encoded using a simple encoding.
Note in the examples below, some characters such as '\n', '\t', and '\r' can be represented as XML entities when used in text but not in element names. Other characters such as '\b' and '\f' cannot be encoded in XML 1.0 at all without inventing our own notation.
Whitespace characters in element names are encoded as well as whitespace end characters in text.

Java XML
class BeanWithSpecialCharacters { public String a = " \b\f\n\t\r "; } <object> <a>_x0020_ _x0008__x000C_&#x000a;&#x0009;&#x000d; _x0020_</a> </object>
@Bean(typeName=" \b\f\n\t\r ") class BeanWithNamesWithSpecialCharacters { @BeanProperty(name=" \b\f\n\t\r ") public String a = " \b\f\n\t\r "; } <_x0020__x0020__x0008__x000C__x000A__x0009__x000D__x0020__x0020_> <_x0020__x0020__x0008__x000C__x000A__x0009__x000D__x0020__x0020_> _x0020_ _x0008__x000C_&#x000a;&#x0009;&#x000d; _x0020_ </_x0020__x0020__x0008__x000C__x000A__x0009__x000D__x0020__x0020_> </_x0020__x0020__x0008__x000C__x000A__x0009__x000D__x0020__x0020_>

While it's true that these characters CAN be represented in XML 1.1, it's impossible to parse XML 1.1 text in Java without the XML containing an XML declaration.
Unfortunately, this, and the uselessness of the XMLInputFactory.IS_REPLACING_ENTITY_REFERENCES setting in Java forced us to make some hard design decisions that may not be the most elegant.

2.20.5 - @Xml(childName) Annotation

The @Xml(childName) annotation can be used to specify the name of XML child elements for bean properties of type collection or array.

Example
Data type JSON example Without annotation With annotation
class MyBean { @Xml(childName="X") public String[] a; @Xml(childName="Y") public int[] b; } { a: ['foo','bar'], b: [123,456] } <object> <a> <string>foo</string> <string>bar</string> </a> <b> <number>123</number> <number>456</number> </b> </object> <object> <a> <X>foo</X> <X>bar</X> </a> <b> <Y>123</Y> <Y>456</Y> </b> </object>
class MyBean { @Xml(childName="child") public int[] a; } { a: [123,456] } <object> <a> <string>foo</string> <string>bar</string> </a> </object> <object> <a> <child>foo</child> <child>bar</child> </a> </object>

2.20.6 - @Xml(format) Annotation

The @Xml(format) annotation can be used to tweak the XML format of a POJO.
The value is set to an enum value of type XmlFormat.
This annotation can be applied to both classes and bean properties.

The XmlFormat.ATTR format can be applied to bean properties to serialize them as XML attributes instead of elements.
Note that this only supports properties of simple types (e.g. strings, numbers, booleans).

Example
Data type JSON example Without annotation With annotation
class MyBean { @Xml(format=XmlFormat.ATTR) public String a; } { a: 'foo' } <object> <a>foo</a> </object> <object a='foo'/>

The XmlFormat.ATTRS format can be applied to bean classes to force all bean properties to be serialized as XML attributes instead of child elements.

Example
Data type JSON example Without annotation With annotation
@Xml(format=XmlFormat.ATTRS) class MyBean { public String a; public int b; } { a: 'foo', b: 123 } <object> <a>foo</a> <b>123</b> </object> <object a='foo' b='123'/>

The XmlFormat.ELEMENT format can be applied to bean properties to override the XmlFormat.ATTRS format applied on the bean class.

Example
Data type JSON example Without annotation With annotation
@Xml(format=XmlFormat.ATTRS) class MyBean { public String a; @Xml(format=XmlFormat.ELEMENT) public int b; } { a: 'foo', b: 123 } <object> <a>foo</a> <b>123</b> </object> <object a='foo'> <b>123</b> </object>

The XmlFormat.ATTRS format can be applied to a single bean property of type Map<String,Object> to denote arbitrary XML attribute values on the element.
These can be mixed with other XmlFormat.ATTR annotated properties, but there must not be an overlap in bean property names and map keys.

Example
Data type JSON example Without annotation With annotation
class MyBean { @Xml(format=XmlFormat.ATTRS) public Map<String,Object> a; @Xml(format=XmlFormat.ATTR) public int b; } { a: { k1: 'foo', k2: 123, }, b: 456 } <object> <a> <k1>foo</k1> <k2 _type='number'>123</k2> </a> <b>456</b> </object> <object k1='foo' k2='123' b='456'/>

The XmlFormat.COLLAPSED format can be applied to bean properties of type array/Collection.
This causes the child objects to be serialized directly inside the bean element.
This format must be used in conjunction with @Xml(childName) to differentiate which collection the values came from if you plan on parsing the output back into beans.
Note that child names must not conflict with other property names.

Data type JSON example Without annotation With annotation
class MyBean { @Xml(childName="A",format=XmlFormat.COLLAPSED) public String[] a; @Xml(childName="B",format=XmlFormat.COLLAPSED) public int[] b; } { a: ['foo','bar'], b: [123,456] } <object> <a> <string>foo</string> <string>bar</string> </a> <b> <number>123</number> <number>456</number> </b> </object> <object> <A>foo</A> <A>bar</A> <B>123</B> <B>456</B> </object>

The XmlFormat.ELEMENTS format can be applied to a single bean property of either a simple type or array/Collection.
It allows free-form child elements to be formed.
All other properties on the bean MUST be serialized as attributes.

Data type JSON example With annotation
class MyBean { @Xml(format=XmlFormat.ATTR) public String a; @Xml(format=XmlFormat.ELEMENTS) public String b; } { a: 'foo', b: 'bar' } <object a='foo'> <string>bar</string> </object>
class MyBean { @Xml(format=XmlFormat.ATTR) public String a; @Xml(format=XmlFormat.ELEMENTS) public Object[] b; } { a: 'foo', b: [ 'bar', 'baz', 123, true, null ] } <object a='foo'> <string>bar</string> <string>baz</string> <number>123</number> <boolean>true</boolean> <null/> </object>

The XmlFormat.MIXED format is similar to XmlFormat.ELEMENTS except elements names on primitive types (string/number/boolean/null) are stripped from the output.
This format particularly useful when combined with bean dictionaries to produce mixed content.
The bean dictionary isn't used during serialization, but it is needed during parsing to resolve bean types.

The XmlFormat.MIXED_PWS format identical to XmlFormat.MIXED except whitespace characters are preserved in the output.

Data type JSON example Without annotations With annotations
class MyBean { @Xml(format=XmlFormat.MIXED) @BeanProperty(beanDictionary={MyBeanX.class, MyBeanY.class}) public Object[] a; } @Bean(typeName="X") class MyBeanX { @Xml(format=XmlFormat.ATTR) public String b; } @Bean(typeName="Y") class MyBeanY { @Xml(format=XmlFormat.ATTR) public String c; } { a: [ 'foo', { _type:'X', b:'bar' } 'baz', { _type:'Y', b:'qux' }, 'quux' ] } <object> <a> <string>foo</string> <object> <b>bar</b> </object> <string>baz</string> <object> <b>qux</b> </object> <string>quux</string> </a> </object> <object>foo<X b='bar'/>baz<Y c='qux'/>quux</object>

Whitespace (tabs and newlines) are not added to MIXED child nodes in readable-output mode.
This helps ensures strings in the serialized output can be losslessly parsed back into their original forms when they contain whitespace characters.
If the XMLInputFactory.IS_REPLACING_ENTITY_REFERENCES setting was not useless in Java, we could support lossless readable XML for MIXED content.
But as of Java 8, it still does not work.

XML suffers from other deficiencies as well that affect MIXED content.
For example, <X></X> and <X/> are equivalent in XML and indistinguishable by the Java XML parsers.
This makes it impossible to differentiate between an empty element and an element containing an empty string.
This causes empty strings to get lost in translation.
To alleviate this, we use the constructs "_xE000_" to represent an empty string, and "_x0020_" to represent leading and trailing spaces.

The examples below show how whitespace is handled under various circumstances:

Data type XML
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.TEXT) public String a = null; } <X/>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.TEXT) public String a = ""; } <X>_xE000_</X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.TEXT) public String a = " "; } <X>_x0020_</X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.TEXT) public String a = " "; } <X>_x0020__x0020_</X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.TEXT) public String a = " foobar "; } <X>_x0020_ foobar _x0020_</X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.TEXT_PWS) public String a = null; } <X/>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.TEXT_PWS) public String a = ""; } <X>_xE000_</X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.TEXT_PWS) public String a = " "; } <X> </X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.TEXT_PWS) public String a = " "; } <X> </X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.TEXT_PWS) public String a = " foobar "; } <X> foobar </X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.MIXED) public String[] a = null; } <X/>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.MIXED) public String a[] = new String[]{""}; } <X>_xE000_</X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.MIXED) public String a[] = new String[]{" "}; } <X>_x0020_</X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.MIXED) public String a[] = new String[]{" "}; } <X>_x0020__x0020_</X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.MIXED) public String a[] = new String[]{ " foobar " }; } <X>_x0020_ foobar _x0020_</X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.MIXED_PWS) public String[] a = null; } <X/>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.MIXED_PWS) public String a[] = new String[]{""}; } <X>_xE000_</X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.MIXED_PWS) public String a[] = new String[]{" "}; } <X> </X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.MIXED_PWS) public String a[] = new String[]{" "}; } <X> </X>
@Bean(typeName="X") class MyBean { @Xml(format=XmlFormat.MIXED_PWS) public String a[] = new String[]{ " foobar " }; } <X> foobar </X>

It should be noted that when using MIXED, you are not guaranteed to parse back the exact same content since side-by-side strings in the content will end up concatenated when parsed.

The XmlFormat.TEXT format is similar to XmlFormat.MIXED except it's meant for solitary objects that get serialized as simple child text nodes.
Any object that can be serialize to a String can be used.
The XmlFormat.TEXT_PWS is the same except whitespace is preserved in the output.

Data type JSON example Without annotations With annotations
class MyBean { @Xml(format=XmlFormat.TEXT) public String a; } { a: 'foo' } <object> <a>foo</a> </object> <object>foo</object>

The XmlFormat.XMLTEXT format is similar to XmlFormat.TEXT except it's meant for strings containing XML that should be serialized as-is to the document.
Any object that can be serialize to a String can be used.
During parsing, the element content gets parsed with the rest of the document and then re-serialized to XML before being set as the property value. This process may not be perfect (e.g. double quotes may be replaced by single quotes, etc...).

Data type JSON example With TEXT annotation With XMLTEXT annotation
class MyBean { @Xml(format=XmlFormat.XMLTEXT) public String a; } { a: 'Some <b>XML</b> text' } <object>Some &lt;b&gt;XML&lt;/b&gt; text</object> <object>Some <b>XML</b> text</object>

2.20.7 - Namespaces

Let's go back to the example of our original Person bean class, but add some namespace annotations:

Sample Beans

@Xml(prefix="per") @Bean(typeName="person") public class Person { // Bean properties public String name; @Swap(CalendarSwap.ISO8601DTZ.class) public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } @Xml(prefix="addr") @Bean(typeName="address") public class Address { // Bean properties @Xml(prefix="mail") public String street, city; @Xml(prefix="mail") public StateEnum state; @Xml(prefix="mail") public int zip; public boolean isCurrent; // Getters/setters omitted }

The namespace URLs can either be defined as part of the @Xml annotation, or can be defined at the package level with the @XmlSchema annotation.
Below shows it defined at the package level:

package-info.java

@XmlSchema( prefix="ab", // Default namespace xmlNs={ @XmlNs(prefix="ab", namespaceURI="http://www.apache.org/addressBook/"), @XmlNs(prefix="per", namespaceURI="http://www.apache.org/person/"), @XmlNs(prefix="addr", namespaceURI="http://www.apache.org/address/"), @XmlNs(prefix="mail", namespaceURI="http://www.apache.org/mail/") } ) package org.apache.juneau.examples.addressbook;

Sample Code

Person p = new Person() .name("John Smith") .birthDate("1946-08-12T00:00:00Z") .addresses( new Address() .street("100 Main Street") .city("Anywhereville") .state(NY) .zip(12345) .isCurrent(true); ); // Create a new serializer with readable output, this time with namespaces enabled. // Note that this is identical to XmlSerializer.DEFAULT_NS_SQ_READABLE. XmlSerializer s = XmlSerializer.create().ns().ws().sq().build(); String xml = s.serialize(p);

Now when we run this code, we'll see namespaces added to our output:

<per:person> <per:name>John Smith</per:name> <per:birthDate>1946-08-12T04:00:00Z</per:birthDate> <per:addresses> <addr:address> <mail:street>100 Main Street</mail:street> <mail:city>Anywhereville</mail:city> <mail:state>NY</mail:state> <mail:zip>12345</mail:zip> <addr:isCurrent>true</addr:isCurrent> </addr:address> </per:addresses> </per:person>

Enabling the XmlSerializer.XML_addNamespaceUrisToRoot setting results in the namespace URLs being added to the root node:

<per:person xmlns='http://www.apache.org/2013/Juneau' xmlns:per='http://www.apache.org/person/' xmlns:addr='http://www.apache.org/address/' xmlns:mail='http://www.apache.org/mail/' > <per:name>John Smith</per:name> <per:birthDate>1946-08-12T04:00:00Z</per:birthDate> <per:addresses> <addr:address> <mail:street>100 Main Street</mail:street> <mail:city>Anywhereville</mail:city> <mail:state>NY</mail:state> <mail:zip>12345</mail:zip> <addr:isCurrent>true</addr:isCurrent> </addr:address> </per:addresses> </per:person>

We can simplify the output by setting the default namespace on the serializer so that all the elements do not need to be prefixed:

// Create a new serializer with readable output, this time with namespaces enabled. XmlSerializer s = XmlSerializer.create().ws().sq().ns() .defaultNamespaceUri("http://www.apache.org/person/") .build();

This produces the following equivalent where the elements don't need prefixes since they're already in the default document namespace:

<person xmlns:juneau='http://www.apache.org/2013/Juneau' xmlns='http://www.apache.org/person/' xmlns:addr='http://www.apache.org/address/' xmlns:mail='http://www.apache.org/mail/' > <name>John Smith</name> <birthDate>1946-08-12T04:00:00Z</birthDate> <addresses> <addr:address> <mail:street>100 Main Street</mail:street> <mail:city>Anywhereville</mail:city> <mail:state>NY</mail:state> <mail:zip>12345</mail:zip> <addr:isCurrent>true</addr:isCurrent> </addr:address> </addresses> </person>

One important property on the XML serializer class is XML_autoDetectNamespaces.
This property tells the serializer to make a first-pass over the data structure to look for namespaces defined on classes and bean properties.
In high-performance environments, you may want to consider disabling auto-detection and providing your own explicit list of namespaces to the serializer to avoid this scanning step.

The following code will produce the same output as before, but will perform slightly better since it avoids this pre-scan step.

// Create a new serializer with readable output, this time with namespaces enabled. XmlSerializer s = XmlSerializer.create() .ws() .sq() .autoDetectNamespaces(false) .namespaces("{per:'http://www.apache.org/person/'}") .build();

2.20.8 - XML-Schema Support

Juneau provides the XmlSchemaSerializer class for generating XML-Schema documents that describe the output generated by the XmlSerializer class.
This class shares the same properties as XmlSerializer.
Since the XML output differs based on settings on the XML serializer class, the XML-Schema serializer class must have the same property values as the XML serializer class it's describes.
To help facilitate creating an XML Schema serializer with the same properties as the corresponding XML serializer, the XmlSerializer.getSchemaSerializer() method has been added.

XML-Schema requires a separate file for each namespace.
Unfortunately, does not mesh well with the Juneau serializer architecture which serializes to single writers.
To get around this limitation, the schema serializer will produce a single output, but with multiple schema documents separated by the null character ('\u0000') to make it simple to split apart.

Lets start with an example where everything is in the same namespace.
We'll use the classes from before, but remove the references to namespaces.
Since we have not defined a default namespace, everything is defined under the default Juneau namespace.

Sample Beans

@Bean(typeName="person") public class Person { // Bean properties public String name; @Swap(CalendarSwap.ISO8601DTZ.class) public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } @Bean(typeName="address") public class Address { // Bean properties public String street, city; public StateEnum state; public int zip; public boolean isCurrent; // Getters/setters omitted }

The code for creating our POJO model and generating XML Schema is shown below:

// Create a new serializer with readable output. XmlSerializer s = XmlSerializer.create() .ws() .ns() .sq() .addNamespaceUrisToRoot(true) .build(); // Create the equivalent schema serializer. XmlSchemaSerializer ss = s.getSchemaSerializer(); // Get the XML Schema corresponding to the XML generated above. String xmlSchema = ss.serialize(new Person());

XML-Schema results

<schema xmlns='http://www.w3.org/2001/XMLSchema' targetNamespace='http://www.apache.org/2013/Juneau' elementFormDefault='qualified' xmlns:juneau='http://www.apache.org/2013/Juneau'> <element name='person' _type='juneau:org.apache.juneau.examples.addressbook.Person'/> <complexType name='org.apache.juneau.examples.addressbook.Person'> <sequence> <element name='name' _type='string' minOccurs='0'/> <element name='birthDate' _type='juneau:java.util.Calendar' minOccurs='0'/> <element name='addresses' _type='juneau:java.util.LinkedList_x003C_org.apache.juneau.examples.addressbook.Address_x003E_' minOccurs='0'/> </sequence> </complexType> <complexType name='java.util.Calendar'> <sequence> <any processContents='skip' maxOccurs='unbounded' minOccurs='0'/> </sequence> </complexType> <complexType name='java.util.LinkedList_x003C_org.apache.juneau.examples.addressbook.Address_x003E_'> <sequence> <choice minOccurs='0' maxOccurs='unbounded'> <element name='address' _type='juneau:org.apache.juneau.examples.addressbook.Address'/> <element name='null' _type='string'/> </choice> </sequence> </complexType> <complexType name='org.apache.juneau.examples.addressbook.Address'> <sequence> <element name='street' _type='string' minOccurs='0'/> <element name='city' _type='string' minOccurs='0'/> <element name='state' _type='string' minOccurs='0'/> <element name='zip' _type='integer' minOccurs='0'/> <element name='isCurrent' _type='boolean' minOccurs='0'/> </sequence> </complexType> </schema>

Now if we add in some namespaces, we'll see how multiple namespaces are handled.

Sample Beans with multiple namespaces

@Xml(prefix="per") @Bean(typeName="person") public class Person { // Bean properties public String name; @Swap(CalendarSwap.ISO8601DTZ.class) public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } @Xml(prefix="addr") @Bean(typeName="address") public class Address { // Bean properties @Xml(prefix="mail") public String street, city; @Xml(prefix="mail") public StateEnum state; @Xml(prefix="mail") public int zip; public boolean isCurrent; // Getters/setters omitted }

The schema consists of 4 documents separated by a '\u0000' character.

XML-Schema results

<schema xmlns='http://www.w3.org/2001/XMLSchema' targetNamespace='http://www.apache.org/2013/Juneau' elementFormDefault='qualified' xmlns:juneau='http://www.apache.org/2013/Juneau' xmlns:per='http://www.apache.org/person/' xmlns:addr='http://www.apache.org/address/' xmlns:mail='http://www.apache.org/mail/'> <import namespace='http://www.apache.org/person/' schemaLocation='per.xsd'/> <import namespace='http://www.apache.org/address/' schemaLocation='addr.xsd'/> <import namespace='http://www.apache.org/mail/' schemaLocation='mail.xsd'/> <complexType name='int'> <simpleContent> <extension base='integer'/> </simpleContent> </complexType> <complexType name='java.lang.String'> <simpleContent> <extension base='string'/> </simpleContent> </complexType> <complexType name='java.net.URI'> <simpleContent> <extension base='string'/> </simpleContent> </complexType> <complexType name='java.util.Calendar'> <sequence> <any processContents='skip' maxOccurs='unbounded' minOccurs='0'/> </sequence> </complexType> <complexType name='java.util.LinkedList_x003C_org.apache.juneau.examples.addressbook.Address_x003E_'> <sequence> <choice minOccurs='0' maxOccurs='unbounded'> <element name='address' _type='addr:org.apache.juneau.examples.addressbook.Address'/> <element name='null' _type='string'/> </choice> </sequence> </complexType> <complexType name='boolean'> <simpleContent> <extension base='boolean'/> </simpleContent> </complexType> </schema> [\u0000] <schema xmlns='http://www.w3.org/2001/XMLSchema' targetNamespace='http://www.apache.org/person/' elementFormDefault='qualified' attributeFormDefault='qualified' xmlns:juneau='http://www.apache.org/2013/Juneau' xmlns:per='http://www.apache.org/person/' xmlns:addr='http://www.apache.org/address/' xmlns:mail='http://www.apache.org/mail/'> <import namespace='http://www.apache.org/2013/Juneau' schemaLocation='juneau.xsd'/> <import namespace='http://www.apache.org/address/' schemaLocation='addr.xsd'/> <import namespace='http://www.apache.org/mail/' schemaLocation='mail.xsd'/> <element name='person' _type='per:org.apache.juneau.examples.addressbook.Person'/> <complexType name='org.apache.juneau.examples.addressbook.Person'> <sequence> <any minOccurs='0' maxOccurs='unbounded'/> </sequence> <attribute name='uri' _type='string'/> </complexType> <element name='name' _type='juneau:java.lang.String'/> <element name='birthDate' _type='juneau:java.util.Calendar'/> <element name='addresses' _type='juneau:java.util.LinkedList_x003C_org.apache.juneau.examples.addressbook.Address_x003E_'/> </schema> [\u0000] <schema xmlns='http://www.w3.org/2001/XMLSchema' targetNamespace='http://www.apache.org/address/' elementFormDefault='qualified' attributeFormDefault='qualified' xmlns:juneau='http://www.apache.org/2013/Juneau' xmlns:per='http://www.apache.org/person/' xmlns:addr='http://www.apache.org/address/' xmlns:mail='http://www.apache.org/mail/'> <import namespace='http://www.apache.org/2013/Juneau' schemaLocation='juneau.xsd'/> <import namespace='http://www.apache.org/person/' schemaLocation='per.xsd'/> <import namespace='http://www.apache.org/mail/' schemaLocation='mail.xsd'/> <complexType name='org.apache.juneau.examples.addressbook.Address'> <sequence> <any minOccurs='0' maxOccurs='unbounded'/> </sequence> </complexType> <element name='isCurrent' _type='juneau:boolean'/> </schema> [\u0000] <schema xmlns='http://www.w3.org/2001/XMLSchema' targetNamespace='http://www.apache.org/mail/' elementFormDefault='qualified' attributeFormDefault='qualified' xmlns:juneau='http://www.apache.org/2013/Juneau' xmlns:per='http://www.apache.org/person/' xmlns:addr='http://www.apache.org/address/' xmlns:mail='http://www.apache.org/mail/'> <import namespace='http://www.apache.org/2013/Juneau' schemaLocation='juneau.xsd'/> <import namespace='http://www.apache.org/person/' schemaLocation='per.xsd'/> <import namespace='http://www.apache.org/address/' schemaLocation='addr.xsd'/> <element name='street' _type='juneau:java.lang.String'/> <element name='city' _type='juneau:java.lang.String'/> <element name='state' _type='juneau:java.lang.String'/> <element name='zip' _type='juneau:int'/> </schema>

For convenience, the #getValidator(SerializerSession,Object) method is provided to create a Validator using the input from the serialize method.

2.21 - HTML Details

Juneau supports converting arbitrary POJOs to and from HTML. Built on top of the existing XML parser, it also uses a STaX parser and creates POJOs directly without intermediate DOM objects.

The primary use case for HTML serialization is rendering POJOs in easy-to-read format in REST interfaces.

2.21.1 - HTML Methodology

The following examples show how different data types are represented in HTML. They mirror how the data structures are represented in JSON.

Simple types

The representation for simple types mirror those produced by the XML serializer. Tags are added to help differentiate data types when they cannot be inferred through reflection. These tags are ignored by browsers and treated as plain text.

Data type JSON example HTML
string 'foo' <string>foo</string>
boolean true <boolean>true</boolean>
integer 123 <number>123</number>
float 1.23 <number>1.23</number>
null null <null/>
Maps

Maps and beans are represented as tables.

The _type attribute is added to differentiate between objects (maps/beans) and arrays (arrays/collections).

Data type JSON example HTML
Map<String,String> { k1: 'v1' k2: null } <table _type='object'> <tr> <td>k1</td> <td>v1</td> </tr> <tr> <td>k2</td> <td><null/></td> </tr> </table>
Map<String,Number> { k1: 123, k2: 1.23, k3: null } <table _type='object'> <tr> <td>k1</td> <td>123</td> </tr> <tr> <td>k2</td> <td>1.23</td> </tr> <tr> <td>k3</td> <td><null/></td> </tr> </table>
Map<String,Object> { k1: 'v1' k2: 123, k3: 1.23, k4: true, k5: null } <table _type='object'> <tr> <td>k1</td> <td>v1</td> </tr> <tr> <td>k2</td> <td><number>123</number></td> </tr> <tr> <td>k3</td> <td><number>1.23</number></td> </tr> <tr> <td>k4</td> <td><boolean>true</boolean></td> </tr> <tr> <td>k5</td> <td><null/></td> </tr> </table>
Arrays

Collections and arrays are represented as ordered lists.

Data type JSON example HTML
String[] [ 'foo' null ] <ul> <li>foo</li> <li><null/></li> </ul>
Number[] [ 123, 1.23, null ] <ul> <li>123</li> <li>1.23</li> <li><null/></li> </ul>
Object[] [ 'foo', 123, 1.23, true, null ] <ul> <li>foo</li> <li><number>123</number></li> <li><number>1.23</number></li> <li><boolean>true</boolean></li> <li><null/></li> </ul>
String[][] [ ['foo', null], null, ] <ul> <li> <ul> <li>foo</li> <li><null/></li> </ul> </li> <li><null/></li> </ul>
int[] [ 123 ] <ul> <li>123</li> </ul>
boolean[] [ true ] <ul> <li>true</li> </ul>
Collections
Data type JSON example HTML
List<String> [ 'foo' null ] <ul> <li>foo</li> <li><null/></li> </ul>
List<Number> [ 123, 1.23, null ] <ul> <li>123</li> <li>1.23</li> <li><null/></li> </ul>
List<Object> [ 'foo', 123, 1.23, true, null ] <ul> <li>foo</li> <li><number>123</number></li> <li><number>1.23</number></li> <li><boolean>true</boolean></li> <li><null/></li> </ul>
Beans
Data type JSON example HTML
class MyBean { public String a; public int b; public Object c; // String value public Object d; // Integer value public MyBean2 e; public String[] f; public int[] g; } class MyBean2 { String h; } { a: 'foo', b: 123, c: 'bar', d: 456, e: { h: 'baz' } f: ['qux'] g: [789] } <table _type='object'> <tr> <td>a</td> <td>foo</td> </tr> <tr> <td>b</td> <td>123</td> </tr> <tr> <td>c</td> <td>bar</td> </tr> <tr> <td>d</td> <td><number>456</number></td> </tr> <tr> <td>e</td> <td> <table _type='object'> <tr> <td>h</td> <td>qux</td> </tr> </table> </td> </tr> <tr> <td>f</td> <td> <ul> <li>baz</li> </ul> </td> </tr> <tr> <td>g</td> <td> <ul> <li>789</li> </ul> </td> </tr> </table>
Beans with Map properties
Data type JSON example HTML
class MyBean { public Map<String,String> a; public Map<String,Number> b; public Map<String,Object> c; } { a: { k1: 'foo' }, b: { k2: 123 }, c: { k3: 'bar', k4: 456, k5: true, k6: null } } <table _type='object'> <tr> <td>a</td> <td> <table _type='object'> <tr> <td>k1</td> <td>foo</td> </tr> </table> </td> </tr> <tr> <td>b</td> <td> <table _type='object'> <tr> <td>k2</td> <td>123</td> </tr> </table> </td> </tr> <tr> <td>c</td> <td> <table _type='object'> <tr> <td>k3</td> <td>bar</td> </tr> <tr> <td>k4</td> <td><number>456</number></td> </tr> <tr> <td>k5</td> <td><boolean>true</boolean></td> </tr> <tr> <td>k6</td> <td><null/></td> </tr> </table> </td> </tr> </table>

2.21.2 - HTML Serializers

2.21.3 - HTML Parsers

The HtmlParser class is used to parse HTML into POJOs.
They can also parse the contents produced by HtmlDocSerializer.

The HTML parser provides the following settings:

The following pre-configured parsers are provided for convenience:

2.21.4 - @Html Annotation

The @Html annotation can be used to customize how POJOs are serialized to HTML on a per-class/field/method basis.

The @Html(link) annotation adds a hyperlink to a bean property when rendered as HTML.

Example:

public class FileSpace { // Add a hyperlink to this bean property. @Html(link="servlet:/drive/{drive}") public String getDrive() {...} }

The @Html(anchorText) annotation is used to specify the anchor text of a hyperlink.

Example:

// Produces <a href='...'>CLICK ME!</a> when serialized to HTML. public class FileSpace { // Add a hyperlink to this bean property. @Html(link="servlet:/drive/{drive}", anchorText="CLICK ME!") public String getDrive() {...} }

The @Html(format) annotation is used to specify what format to use for HTML elements.
For example, the HTML beans defined in the org.apache.juneau.dto.html5 package use format=XML so that the beans get serialized as standard XML:

Example:

// Parent class of all HTML DTO beans. @Html(format=XML) public abstract class HtmlElement {...}

The @Html(noTableHeaders) annotation is used to prevent beans from being serialized with table headers.

The @Html(noTables) annotation is used to force beans to be serialized as trees instead of tables

2.21.5 - @Html(render) Annotation

The @Html(render) annotation allows for custom rendering of bean property values when serialized as HTML. Using this class, you can alter the CSS style and HTML content of the bean property.

The following example shows two render classes that customize the appearance of the pctFull and status columns in the code below:

import static org.apache.juneau.dto.html5.HtmlBuilder.*; // Our bean class public class FileSpace { private final String drive; private final long total, available; public FileSpace(String drive, long total, long available) { this.drive = drive; this.total = total; this.available = available; } @Html(link="drive/{drive}") public String getDrive() { return drive; } public long getTotal() { return total; } public long getAvailable() { return available; } @Html(render=FileSpacePctRender.class) public float getPctFull() { return ((100 * available) / total); } @Html(render=FileSpaceStatusRender.class) public FileSpaceStatus getStatus() { float pf = getPctFull(); if (pf < 80) return FileSpaceStatus.OK; if (pf < 90) return FileSpaceStatus.WARNING; return FileSpaceStatus.SEVERE; } }

// Possible values for the getStatus() method public enum FileSpaceStatus { OK, WARNING, SEVERE; }

// Custom render for getPctFull() method public class FileSpacePctRender extends HtmlRender<Float> { @Override public String getStyle(SerializerSession session, Float value) { if (value < 80) return "background-color:lightgreen;text-align:center"; if (value < 90) return "background-color:yellow;text-align:center"; return "background-color:red;text-align:center;border:;animation:color_change 0.5s infinite alternate"; } @Override public Object getContent(SerializerSession session, Float value) { if (value >= 90) return div( String.format("%.0f%%", value), style("@keyframes color_change { from { background-color: red; } to { background-color: yellow; }") ); return String.format("%.0f%%", value); } }

// Custom render for getStatus() method public class FileSpaceStatusRender extends HtmlRender<FileSpaceStatus> { @Override public String getStyle(SerializerSession session, FileSpaceStatus value) { return "text-align:center"; } @Override public Object getContent(SerializerSession session, FileSpaceStatus value) { switch (value) { case OK: return img().src(URI.create("servlet:/htdocs/ok.png")); case WARNING: return img().src(URI.create("servlet:/htdocs/warning.png")); default: return img().src(URI.create("servlet:/htdocs/severe.png")); } } }

2.21.6 - HtmlDocSerializer

HtmlDocSerializer is an extension of HtmlSerializer that wraps serialized POJOs in a complete HTML document.

This class is used extensively in the creation of POJO-based user interfaces in the REST API.

Example:

/** * Sample REST resource that prints out a simple "Hello world!" message. */ @RestResource( path="/helloWorld", htmldoc=@HtmlDoc( navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS" }, aside={ "<div style='max-width:400px' class='text'>", " <p>This page shows a resource that simply response with a 'Hello world!' message</p>", " <p>The POJO serialized is a simple String.</p>", "</div>" } ) ) public class HelloWorldResource extends BasicRestServlet {...}

The HTMLDOC_template setting defines a template for the HTML page being generated. The default template is described next.

2.21.7 - BasicHtmlDocTemplate

The BasicHtmlDocTemplate class defines a default template for HTML documents created by HtmlDocSerializer.

The HTML document created by this template consists of the following structure:

<html> <head> <style type='text/css'> CSS styles and links to stylesheets </style> </head> <body> <header> Page header </header> <nav> Navigation links </nav> <aside> Side-bar text </aside> <article> Contents of serialized object </article> <footer> Footer message </footer> </body> </html>

2.21.8 - Custom Templates

Custom page templates can be created by implementing the HtmlDocTemplate interface and associating it with your HtmlDocSerializer using the HTMLDOC_template setting.

The interface implementation is open-ended allowing you to define the contents of the page any way you wish.

2.21.9 - HTML-Schema Support

The HtmlSchemaSerializer class is the HTML-equivalent to the JsonSchemaSerializer class. It's used to generate HTML versions of JSON-Schema documents that describe the output generated by the JsonSerializer class.

Sample Beans

public class Person { // Bean properties public String name; public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } public class Address { // Bean properties public String street, city; public StateEnum state; public int zip; public boolean isCurrent; // Getters/setters omitted }

The code for creating our POJO model and generating HTML-Schema is shown below:

// Get the one of the default schema serializers. HtmlSchemaSerializer s = HtmlSchemaSerializer.DEFAULT_SIMPLE_READABLE; // Get the HTML Schema for the POJO. String htmlSchema = s.serialize(new Person()); // This also works. htmlSchema = s.serialize(Person.class);

The result is the HTML table shown below:

type object
properties
name
type string
birthDate
type string
addresses
type array
items
type object
properties
street
type string
city
type string
state
type string
enum
  • AL
  • PA
  • NC
zip
type integer
format int32
isCurrent
type boolean

2.22 - UON Details

Juneau supports converting arbitrary POJOs to and from UON strings using ultra-efficient serializers and parsers.
The serializer converts POJOs directly to UON strings without the need for intermediate DOM objects using a highly-efficient state machine.
Likewise, the parser creates POJOs directly from UON strings without the need for intermediate DOM objects.

Juneau uses UON (URL-Encoded Object Notation) for representing POJOs. The UON specification can be found here.

The following example shows JSON for a typical bean:

Sample Beans

public class Person { // Bean properties public String name; @Swap(CalendarSwap.ISO8601DTZ.class) public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } public class Address { // Bean properties public String street, city; public StateEnum state; public int zip; public boolean isCurrent; // Getters/setters omitted }

Sample Code

Person p = new Person() .name("John Smith") .birthDate("1946-08-12T00:00:00Z") .addresses( new Address() .street("100 Main Street") .city("Anywhereville") .state(NY) .zip(12345) .isCurrent(true); );

UON

( name='John+Smith', birthDate='1946-08-12T00:00:00Z', addresses=@( ( street='100 Main Street', city=Anywhereville, state=NY, zip=12345, isCurrent=true ) ) )

2.22.1 - UON Methodology

General methodology:
Java typeJSON equivalentUON
Maps/beans OBJECT a1=(b1=x1,b2=x2) a1=(b1=(c1=x1,c2=x2))
Collections/arrays ARRAY a1=@(x1,x2) a1=@(@(x1,x2),@(x3,x4)) a1=@((b1=x1,b2=x2),(c1=x1,c2=x2))
Booleans BOOLEAN a1=true&a2=false
int/float/double/... NUMBER a1=123&a2=1.23e1
null NULL a1=null
String STRING a1=foobar a1='true' a1='null' a1='123' a1=' string with whitespace ' a1='string with ~'escaped~' quotes'

Refer to the UON specification for a complete set of syntax rules.

2.22.2 - UON Serializers

The UonSerializer class is used to serialize POJOs into UON.

The UON serializers provides the following settings:

The following pre-configured serializers are provided for convenience:

2.22.3 - UON Parsers

The UonParser class is used to parse UON into POJOs.

The UON parser provides the following settings:

The following pre-configured parsers are provided for convenience:

2.23 - URL-Encoding Details

Juneau supports converting arbitrary POJOs to and from URL-encoded strings using ultra-efficient serializers and parsers.
The serializer converts POJOs directly to URL-encoded strings without the need for intermediate DOM objects using a highly-efficient state machine.
Likewise, the parser creates POJOs directly from URL-encoded strings without the need for intermediate DOM objects.

Juneau uses UON (URL-Encoded Object Notation) for representing POJOs as URL-Encoded values in key-value pairs. The UON specification can be found here.

The following example shows JSON for a typical bean:

Sample Beans

public class Person { // Bean properties public String name; @Swap(CalendarSwap.ISO8601DTZ.class) public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } public class Address { // Bean properties public String street, city; public StateEnum state; public int zip; public boolean isCurrent; // Getters/setters omitted }

Sample Code

Person p = new Person() .name("John Smith") .birthDate("1946-08-12T00:00:00Z") .addresses( new Address() .street("100 Main Street") .city("Anywhereville") .state(NY) .zip(12345) .isCurrent(true); );

URL-Encoding

name='John+Smith' &birthDate='1946-08-12T00:00:00Z' &addresses=@( ( street='100 Main Street', city=Anywhereville, state=NY, zip=12345, isCurrent=true ) )

2.23.1 - URL-Encoding Methodology

General methodology:
Java typeJSON equivalentUON
Maps/beans OBJECT a1=(b1=x1,b2=x2) a1=(b1=(c1=x1,c2=x2))
Collections/arrays ARRAY a1=@(x1,x2) a1=@(@(x1,x2),@(x3,x4)) a1=@((b1=x1,b2=x2),(c1=x1,c2=x2))
Booleans BOOLEAN a1=true&a2=false
int/float/double/... NUMBER a1=123&a2=1.23e1
null NULL a1=null
String STRING a1=foobar a1='true' a1='null' a1='123' a1=' string with whitespace ' a1='string with ~'escaped~' quotes'

Refer to the UON specification for a complete set of syntax rules.

2.23.2 - URL-Encoding Serializers

The UrlEncodingSerializer class is used to serialize POJOs into URL-Encoding.

The URL-Encoding serializers provides the following settings:

The following pre-configured serializers are provided for convenience:

2.23.3 - URL-Encoding Parsers

The UrlEncodingParser class is used to parse URL-Encoding into POJOs.

The URL-Encoding parser provides the following settings:

The following pre-configured parsers are provided for convenience:

2.23.4 - @UrlEncoding Annotation

The @UrlEncoding annotation is used to override the behavior of UrlEncodingSerializer on individual bean classes or properties.

The expandedParams setting is used to force bean properties of type array or Collection to be expanded into multiple key/value pairings.
It's identical in behavior to using the UrlEncodingSerializer.URLENC_expandedParams and UrlEncodingParser.URLENC_expandedParams properties, but applies to only individual bean properties.

2.24 - MessagePack Details

Juneau supports converting arbitrary POJOs to and from MessagePack using ultra-efficient serializers and parsers.

MessagePack is a compact binary form of JSON. The serialization support for MessagePack mirrors that of JSON.

2.24.1 - MessagePack Serializers

The MsgPackSerializer class is used to serialize POJOs into MessagePack.

The MessagePack serializer provides the following settings:

The following pre-configured serializers are provided for convenience:

2.24.2 - MessagePack Parsers

The MsgPackParser class is used to parse MessagePack into POJOs.

The MessagePack parser provides the following settings:

The following pre-configured parsers are provided for convenience:

2.25 - OpenAPI Details

Juneau supports converting arbitrary POJOs to and from strings using OpenAPI-based schema rules.

The relevant classes for using OpenAPI-based serialization are:

The HttpPartSchema class is used to define the formatting and validations for a POJO. It's used in conjunction with the serializer and parser to produce and consume HTTP parts based on OpenAPI rules.

Later in the rest-server and rest-client sections, we also describe how the following annotations can be applied to method parameters and class types to define the schema for various HTTP parts:

2.25.1 - OpenAPI Methodology

Unlike the other Juneau serializers and parsers that convert input and output directly to-and-from POJOs, the OpenAPI serializers and parsers use intermediate objects based on the type and format of the schema.

The following table shows the "natural" intermediate type of the object based on the type/format:

TypeFormatIntermediate Java Type
string or empty byte
binary
binary-spaced
byte[]
date
date-time
Calendar
uon No intermediate type.
(serialized directly to/from POJO)
empty String
boolean empty Boolean
integer int32 Integer
int64 Long
number float Float
double Double
array empty Arrays of intermediate types on this list.
uon No intermediate type.
(serialized directly to/from POJO)
object empty Map<String,Object>
uon No intermediate type.
(serialized directly to/from POJO)

The valid POJO types for serializing/parsing are based on the intermediate types above.
As a general rule, any POJOs that are the intermediate type or transformable to or from the intermediate type are valid POJO types.

For example, the following POJO type can be transformed to and from a byte array.

// Sample POJO class convertable to and from a byte[]. public class MyPojo { // Constructor used by parser. public MyPojo(byte[] fromBytes) {...} // toX method used by serializer. public byte[] toBytes() {...} }

This example shows how that POJO can be converted to a BASE64-encoded string.

// Construct a POJO. MyPojo myPojo = ...; // Define a schema. HttpPartSchema schema = HttpPartSchema.create().type("string").format("byte").build(); // Convert POJO to BASE64-encoded string. HttpPartSerializer s = OpenApiSerializer.DEFAULT; String httpPart = s.serialize(schema, myPojo); // Convert BASE64-encoded string back into a POJO. HttpPartParser p = OpenApiParser.DEFAULT; myPojo = p.parse(schema, httpPart, MyPojo.class);

In addition to defining format, the schema also allows for validations of the serialized form.

// Construct a POJO. MyPojo myPojo = ...; // Define a schema. // Serialized string must be no smaller than 100 characters. HttpPartSchema schema = HttpPartSchema.create().type("string").format("byte").minLength(100).build(); // Convert POJO to BASE64-encoded string. HttpPartSerializer s = OpenApiSerializer.DEFAULT; String httpPart; try { httpPart = s.serialize(schema, myPojo); } catch (SchemaValidationException e) { // Oops, output too small. } // Convert BASE64-encoded string back into a POJO. HttpPartParser p = OpenApiParser.DEFAULT; try { myPojo = p.parse(schema, httpPart, MyPojo.class); } catch (SchemaValidationException e) { // Oops, input too small. }

It looks simple, but the implementation is highly sophisticated being able to serialize and parse and validate using complex schemas.

The next sections go more into depth on serializing and parsing various POJO types.

2.25.2 - OpenAPI Serializers

The OpenApiSerializer class is used to convert POJOs to HTTP parts.

Later we'll describe how to use HTTP-Part annotations to define OpenAPI schemas for serialization and parsing of HTTP parts.
The following example is a preview showing an HTTP body defined as pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9"):

@RestMethod(method="POST", path="/2dLongArray") public void post2dLongArray( @Body( schema=@Schema( items=@Items( collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ) ) minLength=1, maxLength=10 ) ) Long[][] body ) {...}

Under-the-covers, this gets converted to the following schema object:

import static org.apache.juneau.httppart.HttpPartSchema.*; HttpPartSchema schema = create() .items( create() .collectionFormat("pipes") .items( create() .collectionFormat("csv") .type("integer") .format("int64") .minimum("0") .maximum("100") .minLength(1) .maxLength=(10) ) ) .build();

The following code shows how the schema above can be used to create our pipe+csv list of numbers:

// Our POJO being serialized. Long[][] input = .... // The serializer to use. HttpPartSerializer s = OpenApiSerializer.DEFAULT; // Convert POJO to a string. try { String httpPart = s.serialize(schema, input); } catch (SchemaValidationException e) { // Oops, one of the restrictions were not met. }

As a general rule, any POJO convertible to the intermediate type for the type/format of the schema can be serialized using the OpenAPI serializer.
Here are the rules of POJO types allowed for various type/format combinations:

TypeFormatValid parameter types
string or empty byte
binary
binary-spaced
  • byte[] (default)
  • InputStream
  • Reader - Read into String and then converted using String.getBytes().
  • Object - Converted to String and then converted using String.getBytes().
  • Any POJO transformable to a byte[] via the following methods:
    • public byte[] toBytes() {...}
    • public byte[] toFoo() {...} (any method name starting with "to")
  • Any POJO transformable to a byte[] via a PojoSwap.
date
date-time
  • Calendar (default)
  • Date
  • Any POJO transformable to a Calendar via the following methods:
    • public Calendar toCalendar() {...}
    • public Calendar toFoo() {...} (any method name starting with "to")
  • Any POJO transformable to a Calendar via a PojoSwap.
uon
empty
  • String (default)
  • Any POJO transformable to a String via the following methods:
    • public String toString() {...}
  • Any POJO transformable to a String via a PojoSwap.
boolean empty
  • Boolean (default)
  • boolean
  • String - Converted to a Boolean.
  • Any POJO transformable to a Boolean via the following methods:
    • public Boolean toBoolean() {...}
    • public Boolean toFoo() {...} (any method name starting with "to")
  • Any POJO transformable to a Boolean via a PojoSwap.
integer int32
  • Integer (default)
  • int
  • String - Converted to an String.
  • Any POJO transformable to an Integer via the following methods:
    • public Integer toInteger() {...}
    • public Integer toFoo() {...} (any method name starting with "to")
  • Any POJO transformable to an Integer via a PojoSwap.
int64
  • Long (default)
  • long
  • String - Converted to a Long.
  • Any POJO transformable to a Long via the following methods:
    • public Long toLong() {...}
    • public Long toFoo() {...} (any method name starting with "to")
  • Any POJO transformable to a Long via a PojoSwap.
number float
  • Float (default)
  • float
  • String - Converted to a Float.
  • Any POJO transformable to a Float via the following methods:
    • public Float toFloat() {...}
    • public Float toFoo() {...} (any method name starting with "to")
  • Any POJO transformable to a Float via a PojoSwap.
double
  • Double (default)
  • double
  • String - Converted to a Double.
  • Any POJO transformable to a Double via the following methods:
    • public Double toDouble() {...}
    • public Double toFoo() {...} (any method name starting with "to")
  • Any POJO transformable to a Double via a PojoSwap.
array empty
  • Arrays or Collections of any defaults on this list.
  • Any POJO transformable to arrays of the default types (e.g. Integer[], Boolean[][], etc...).
    For example:
    • public Boolean[][] toFoo() {...} (any method name starting with "to")
  • Any POJO transformable to arrays of the default types via a PojoSwap
uon
object empty
  • Map<String,Object> (default)
  • Beans with properties of anything on this list.
  • Any POJO transformable to a map via a PojoSwap
uon

For arrays, an example of "Any POJO transformable to arrays of the default types" is:

// Sample POJO class convertable to a Long[][]. public class MyPojo { // toX method used by serializer. public Long[][] to2dLongs() {...} }

In the example above, our POJO class can be used to create our pipe-delimited list of comma-delimited numbers:

// Our POJO being serialized. MyPojo input = .... // The serializer to use. HttpPartSerializer s = OpenApiSerializer.DEFAULT; // Convert POJO to a string. try { String httpPart = s.serialize(schema, input); } catch (SchemaValidationException e) { // Oops, one of the restrictions were not met. }

The object type is not officially part of the OpenAPI standard. However, Juneau supports serializing Maps and beans to HTTP parts using UON notation.

The following shows an example of a bean with several properties of various types.

public class MyBean { private static byte[] FOOB = "foo".getBytes(); public String f1 = "foo"; public byte[] f2 = FOOB; public byte[] f3 = FOOB; public byte[] f4 = FOOB; public Calendar f5 = parseIsoCalendar("2012-12-21T12:34:56Z"); public String f6 = "foo"; public int f7 = 1; public Long f8 = 2l; public float f9 = 1.0; public Double f10 = 1.0; public Boolean f11 = true; public Object fExtra = "1"; }

We define the following schema:

import static org.apache.juneau.httppart.HttpPartSchema.*; HttpPartSchema ps = schema("object") .property("f1", schema("string")) .property("f2", schema("string", "byte")) .property("f3", schema("string", "binary")) .property("f4", schema("string", "binary-spaced")) .property("f5", schema("string", "date-time")) .property("f6", schema("string", "uon")) .property("f7", schema("integer")) .property("f8", schema("integer", "int64")) .property("f9", schema("number")) .property("f10", schema("number", "double")) .property("f11", schema("boolean")) .additionalProperties(schema("integer")) .build();

Then we serialize our bean:

HttpPartSerializer s = OpenApiSerializer.DEFAULT; String httpPart = s.serialize(schema, new MyBean());

The results of this serialization is shown below:

( f1=foo, f2=Zm9v, f3=666F6F, f4='66 6F 6F', f5=2012-12-21T12:34:56Z, f6=foo, f7=1, f8=2, f9=1.0, f10=1.0, f11=true, fExtra=1 )

The following is an example of a bean with various array property types:

public class MyBean { private static byte[] FOOB = "foo".getBytes(); public String[] f1 = new String[]{"a,b",null}, public byte[][] f2 = new byte[][]{FOOB,null}, public byte[][] f3 = new byte[][]{FOOB,null}, public byte[][] f4 = new byte[][]{FOOB,null}, public Calendar[] f5 = new Calendar[]{parseIsoCalendar("2012-12-21T12:34:56Z"),null}, public String[] f6 = new String[]{"a","b",null}, public int[] f7 = new int[]{1,2,null}, public Integer[] f8 = new Integer[]{3,4,null}, public float[] f9 = new float[]{1f,2f,null}, public Float[] f10 = new Float[]{3f,4f,null}, public Boolean[] f11 = new Boolean[]{true,false,null}, public Object[] fExtra = new Object[]{1,"2",null}; }

For this bean, we define the following schema:

HttpPartSchema ps = schema("object") .property("f1", schema("array").items(schema("string"))) .property("f2", schema("array").items(schema("string", "byte"))) .property("f3", schema("array").items(schema("string", "binary"))) .property("f4", schema("array").items(schema("string", "binary-spaced"))) .property("f5", schema("array").items(schema("string", "date-time"))) .property("f6", schema("array").items(schema("string", "uon"))) .property("f7", schema("array").items(schema("integer"))) .property("f8", schema("array").items(schema("integer", "int64"))) .property("f9", schema("array").items(schema("number"))) .property("f10", schema("array").items(schema("number", "double"))) .property("f11", schema("array").items(schema("boolean"))) .additionalProperties(schema("array").items(schema("integer"))) .build();

Serializing this bean produces the following output:

( f1=@('a,b',null), f2=@(Zm9v,null), f4=@(2012-12-21T12:34:56Z,null), f5=@(666F6F,null), f6=@('66 6F 6F',null), f7=@(a,b,null), f8=@(1,2,null), f9=@(3,4,null), f10=@(1.0,2.0,null), f11=@(3.0,4.0,null), f12=@(true,false,null), fExtra=@(1,2,null) )

Other Notes:
  • Array properties can also use CSV/SSV/PIPES for array notation.
    Various notations can be mixed throughout.
  • Schemas and POJOs can be defined arbitrarily deep.
  • Schemas are optional. They can be skipped or partially defined.
  • We make our best attempt to convert the input to the matching type. However, you will get SerializeExceptions if you attempt an impossible conversion. (e.g. trying to serialize the string "foo" as a boolean).

2.25.3 - OpenAPI Parsers

The OpenApiParser class is used to convert HTTP parts back into POJOs.

The following is the previous example of a schema that defines the format of a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9"):

import static org.apache.juneau.httppart.HttpPartSchema.*; HttpPartSchema schema = create() .items( create() .collectionFormat("pipes") .items( create() .collectionFormat("csv") .type("integer") .format("int64") .minimum("0") .maximum("100") .minLength(1) .maxLength=(10) ) ) .build();

The following code shows how the schema above can be used to parse our input into a POJO:

// Our input being parsed. String input = "1,2,3|4,5,6|7,8,9" // The parser to use. HttpPartParser p = OpenApiParser.DEFAULT; // Convert string to a POJO. try { Long[][] pojo = p.parse(schema, input, Long[][].class); } catch (SchemaValidationException e) { // Oops, one of the restrictions were not met. }

As a general rule, any POJO convertible from the intermediate type for the type/format of the schema can be parsed using the OpenAPI parser.
Here are the rules of POJO types allowed for various type/format combinations:

TypeFormatValid parameter types
string or empty byte
binary
binary-spaced
date
date-time
uon
empty
  • String (default)
  • Object - Returns the default String.
  • Any POJO transformable from a String (via constructors, static create methods, or swaps).
boolean empty
integer int32
  • Integer (default)
  • Any subclass of Number
  • Any primitive number: (e.g int, float...)
  • String
  • Object - Returns the default Integer.
  • Any POJO transformable from an Integer (via constructors, static create methods, or swaps).
int64
  • Long (default)
  • Any subclass of Number
  • Any primitive number: (e.g int, float...)
  • String
  • Object - Returns the default Long.
  • Any POJO transformable from an Long (via constructors, static create methods, or swaps).
number float
  • Float (default)
  • Any subclass of Number
  • Any primitive number: (e.g int, float...)
  • String
  • Object - Returns the default Float.
  • Any POJO transformable from an Float (via constructors, static create methods, or swaps).
double
  • Double (default)
  • Any subclass of Number
  • Any primitive number: (e.g int, float...)
  • String
  • Object - Returns the default Double.
  • Any POJO transformable from an Double (via constructors, static create methods, or swaps).
array empty
  • Arrays or Collections of anything on this list.
  • Any POJO transformable from arrays of the default types (e.g. Integer[], Boolean[][], etc...).
uon
object empty
  • Map<String,Object> (default)
  • Beans with properties of anything on this list.
  • Maps with string keys.
uon

For arrays, an example of "Any POJO transformable from arrays of the default types" is:

// Sample POJO class convertable from a Long[][]. public class MyPojo { // Constructor used by parser. public MyPojo(Long[][] from2dLongs) {...} }

In the example above, our POJO class can be constructed from our pipe-delimited list of comma-delimited numbers:

// Our input being parsed. String input = "1,2,3|4,5,6|7,8,9" // The parser to use. HttpPartParser p = OpenApiParser.DEFAULT; // Convert string to a POJO. try { MyPojo pojo = p.parse(schema, input, MyPojo.class); } catch (SchemaValidationException e) { // Oops, one of the restrictions were not met. }

Just like serialization, the object type is not officially part of the OpenAPI standard, but Juneau supports parsing HTTP parts in UON notation to Maps and beans.

The following shows an example of a bean with several properties of various types.

public class MyBean { public String f1; public byte[] f2; public byte[] f3; public byte[] f4; public Calendar f5; public String f6; public int f7; public Long f8; public float f9; public Double f10; public Boolean f11; public Object fExtra; }

We define the following schema again:

import static org.apache.juneau.httppart.HttpPartSchema.*; HttpPartSchema ps = schema("object") .property("f1", schema("string")) .property("f2", schema("string", "byte")) .property("f3", schema("string", "binary")) .property("f4", schema("string", "binary-spaced")) .property("f5", schema("string", "date-time")) .property("f6", schema("string", "uon")) .property("f7", schema("integer")) .property("f8", schema("integer", "int64")) .property("f9", schema("number")) .property("f10", schema("number", "double")) .property("f11", schema("boolean")) .additionalProperties(schema("integer")) .build();

Then we parse our input into our POJO:

String input = "(f1=foo,f2=Zm9v,f3=666F6F,f4='66 6F 6F',f5=2012-12-21T12:34:56Z,f6=foo," + "f7=1,f8=2,f9=1.0,f10=1.0,f11=true,fExtra=1)"; HttpPartParser p = OpenApiParser.DEFAULT; MyBean b = p.parse(schema, input, MyBean.class);

Note that serializing into generic Object properties would have produced similar results:

public class MyBean { public Object f1; public Object f2; public Object f3; public Object f4; public Object f5; public Object f6; public Object f7; public Object f8; public Object f9; public Object f10; public Object f11; public Object fExtra; }

We can also parse into Maps as well:

String input = "(f1=foo,f2=Zm9v,f3=666F6F,f4='66 6F 6F',f5=2012-12-21T12:34:56Z,f6=foo," + "f7=1,f8=2,f9=1.0,f10=1.0,f11=true,fExtra=1)"; HttpPartParser p = OpenApiParser.DEFAULT; ObjectMap m = p.parse(schema, input, ObjectMap.class);

Other Notes:
  • Array properties can also use CSV/SSV/PIPES for array notation.
    Various notations can be mixed throughout.
  • Schemas and POJOs can be defined arbitrarily deep.
  • Schemas are optional. They can be skipped or partially defined.
  • We make our best attempt to convert the output to the matching type. However, you will get ParseExceptions if you attempt an impossible conversion. (e.g. trying to parse the string "foo" into a boolean).

2.26 - Best Practices

  1. Reuse instances of serializers and parsers whenever possible.
    They are designed to be thread safe and maintain internal caches of bean metadata to increase performance.
  2. The BEANTRAVERSE_detectRecursions option on the Serializer class can cause a performance penalty of around 20%.
    Therefore, it's recommended that this option be used only when necessary.
  3. In general, JSON serialization and parsing is about 20% faster than XML. JSON is also more compact than XML.
    MessagePack is fastest and most compact of all.
  4. The RDF parsers are SLOW.
    RDF simply isn't efficient with node traversal, so creating tree structures out of RDF models is highly inefficient.
  5. The Parser methods that take in ClassMeta parameters are slightly faster than methods that take in Class or Object parameters, since the latter methods involve hash lookups to resolve to ClassMeta parameters.

3 - juneau-marshall-rdf

Maven Dependency

<dependency> <groupId>org.apache.juneau</groupId> <artifactId>juneau-marshall-rdf</artifactId> <version>7.2.1</version> </dependency>

Java Library

juneau-marshall-rdf-7.2.1.jar

OSGi Module

org.apache.juneau.marshall.rdf_7.2.1.jar

The juneau-marshall-rdf library provides additional serializers and parsers for RDF. These rely on the Apache Jena library to provide support for the following languages:

  • RDF/XML
  • RDF/XML-Abbrev
  • N-Triple
  • Turtle
  • N3

3.1 - RDF Details

Juneau supports serializing and parsing arbitrary POJOs to and from the following RDF formats:

  • RDF/XML
  • Abbreviated RDF/XML
  • N-Triple
  • Turtle
  • N3

The serializers and parsers work identically to those in juneau-marshall, but are packaged separately so that you don't need to pull in the Jena dependency unless you need it.

// A simple bean public class Person { public String name = "John Smith"; public int age = 21; } // Serialize a bean to JSON, XML, or HTML Person p = new Person(); // 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> String rdfXml = RdfSerializer.DEFAULT_XMLABBREV.serialize(p); // Produces: // @prefix jp: <http://www.apache.org/juneaubp/> . // @prefix j: <http://www.apache.org/juneau/> . // [] jp:age "21" ; // jp:name "John Smith" . String rdfN3 = N3Serializer.DEFAULT.serialize(p); // Produces: // _:A3bf53c85X3aX157cf407e2dX3aXX2dX7ffd <http://www.apache.org/juneaubp/name> "John Smith" . // _:A3bf53c85X3aX157cf407e2dX3aXX2dX7ffd <http://www.apache.org/juneaubp/age> "21" . String rdfNTriple = RdfSerializer.DEFAULT_NTRIPLE.serialize(p);

3.1.1 - RDF Serializers

3.1.2 - RDF Parsers

3.1.3 - @Rdf Annotation

The @Rdf annotation is used to override the behavior of the RDF serializers and parsers on individual bean classes or properties.

3.1.4 - Namespaces

You'll notice in the previous example that Juneau namespaces are used to represent bean property names.
These are used by default when namespaces are not explicitly specified.

The juneau namespace is used for generic names for objects that don't have namespaces associated with them.

The juneaubp namespace is used on bean properties that don't have namespaces associated with them.

The easiest way to specify namespaces is through annotations.
In this example, we're going to associate the prefix 'per' to our bean class and all properties of this class.
We do this by adding the following annotation to our class:

@Rdf(prefix="per") public class Person {

In general, the best approach is to define the namespace URIs at the package level using a package-info.java class, like so:

// RDF namespaces used in this package @RdfSchema( prefix="ab", rdfNs={ @RdfNs(prefix="ab", namespaceURI="http://www.apache.org/addressBook/"), @RdfNs(prefix="per", namespaceURI="http://www.apache.org/person/"), @RdfNs(prefix="addr", namespaceURI="http://www.apache.org/address/"), @RdfNs(prefix="mail", namespaceURI="http://www.apache.org/mail/") } ) package org.apache.juneau.sample.addressbook; import org.apache.juneau.xml.annotation.*;

This assigns a default prefix of "ab" for all classes and properties within the project, and specifies various other prefixes used within this project.

Now when we rerun the sample code, we'll get the following:

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:j="http://www.apache.org/juneau/" xmlns:jp="http://www.apache.org/juneaubp/" xmlns:per="http://www.apache.org/person/"> <rdf:Description> <per:id>1</per:id> <per:name>John Smith</per:name> </rdf:Description> </rdf:RDF>

Namespace auto-detection (XmlSerializer.XML_autoDetectNamespaces) is enabled on serializers by default.
This causes the serializer to make a first-pass over the data structure to look for namespaces.
In high-performance environments, you may want to consider disabling auto-detection and providing an explicit list of namespaces to the serializer to avoid this scanning step.

// Create a new serializer, but manually specify the namespaces. RdfSerializer s = RdfSerializer.create() .xmlabbrev() .set(RdfProperties.RDF_rdfxml_tab, 3) .autoDetectNamespaces(false) .namespaces("{per:'http://www.apache.org/person/'}") .build();

This code change will produce the same output as before, but will perform slightly better since it doesn't have to crawl the POJO tree before serializing the result.

3.1.5 - URI Properties

Bean properties of type java.net.URI or java.net.URL have special meaning to the RDF serializer.
They are interpreted as resource identifiers.

In the following code, we're adding 2 new properties.
The first property is annotated with @BeanProperty to identify that this property is the resource identifier for this bean.
The second un-annotated property is interpreted as a reference to another resource.

public class Person { // Bean properties @Rdf(beanUri=true) public URI uri; public URI addressBookUri; ... // Normal constructor public Person(int id, String name, String uri, String addressBookUri) throws URISyntaxException { this.id = id; this.name = name; this.uri = new URI(uri); this.addressBookUri = new URI(addressBookUri); } }

We alter our code to pass in values for these new properties.

// Create our bean. Person p = new Person(1, "John Smith", "http://sample/addressBook/person/1", "http://sample/addressBook");

Now when we run the sample code, we get the following:

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:j="http://www.apache.org/juneau/" xmlns:jp="http://www.apache.org/juneaubp/" xmlns:per="http://www.apache.org/person/"> <rdf:Description rdf:about="http://sample/addressBook/person/1"> <per:addressBookUri rdf:resource="http://sample/addressBook"/> <per:id>1</per:id> <per:name>John Smith</per:name> </rdf:Description> </rdf:RDF>

The @URI annotation can also be used on classes and properties to identify them as URLs when they're not instances of java.net.URI or java.net.URL (not needed if @Rdf(beanUri=true) is already specified).

The following properties would have produced the same output as before. Note that the @URI annotation is only needed on the second property.

public class Person { // Bean properties @Rdf(beanUri=true) public String uri; @URI public String addressBookUri;

Also take note of the Serializer.SERIALIZER_uriResolution, Serializer.SERIALIZER_uriRelativity, and and Serializer.SERIALIZER_uriContext settings that can be specified on the serializer to resolve relative and context-root-relative URIs to fully-qualified URIs.

This can be useful if you want to keep the URI authority and context root information out of the bean logic layer.

The following code produces the same output as before, but the URIs on the beans are relative.

// Create a new serializer with readable output. RdfSerializer s = RdfSerializer.create() .xmlabbrev() .set(RdfProperties.RDF_rdfxml_tab, 3); .relativeUriBase("http://myhost/sample"); .absolutePathUriBase("http://myhost") .build(); // Create our bean. Person p = new Person(1, "John Smith", "person/1", "/"); // Serialize the bean to RDF/XML. String rdfXml = s.serialize(p);

3.1.6 - Root Property

For all RDF languages, the POJO objects get broken down into simple triplets.
Unfortunately, for tree-structured data like the POJOs shown above, this causes the root node of the tree to become lost.
There is no easy way to identify that person/1 is the root node in our tree once in triplet form, and in some cases it's impossible.

By default, the RdfParser class handles this by scanning all the nodes and identifying the nodes without incoming references.
However, this is inefficient, especially for large models.
And in cases where the root node is referenced by another node in the model by URL, it's not possible to locate the root at all.

To resolve this issue, the property RdfSerializer.RDF_addRootProperty was introduced.
When enabled, this adds a special root attribute to the root node to make it easy to locate by the parser.

To enable, set the RDF_addRootProperty property to true on the serializer:

// Create a new serializer. RdfSerializer s = RdfSerializer.create() .xmlabbrev() .set(RdfProperties.RDF_rdfxml_tab, 3), .addRootProperty(true) .build();

Now when we rerun the sample code, we'll see the added root attribute on the root resource.

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:j="http://www.apache.org/juneau/" xmlns:jp="http://www.apache.org/juneaubp/" xmlns:per="http://www.apache.org/person/" xmlns:mail="http://www.apache.org/mail/" xmlns:addr="http://www.apache.org/address/"> <rdf:Description rdf:about="http://sample/addressBook/person/1"> <j:root>true</j:root> <per:addressBookUri rdf:resource="http://sample/addressBook"/> <per:id>1</per:id> <per:name>John Smith</per:name> <per:addresses> <rdf:Seq> <rdf:li> <rdf:Description rdf:about="http://sample/addressBook/address/1"> <addr:personUri rdf:resource="http://sample/addressBook/person/1"/> <addr:id>1</addr:id> <mail:street>100 Main Street</mail:street> <mail:city>Anywhereville</mail:city> <mail:state>NY</mail:state> <mail:zip>12345</mail:zip> <addr:isCurrent>true</addr:isCurrent> </rdf:Description> </rdf:li> </rdf:Seq> </per:addresses> </rdf:Description> </rdf:RDF>

3.1.7 - Typed Literals

XML-Schema data-types can be added to non-String literals through the RdfSerializer.RDF_addLiteralTypes setting.

To enable, set the RDF_addLiteralTypes property to true on the serializer:

// Create a new serializer (revert back to namespace autodetection). RdfSerializer s = RdfSerializer.create() .xmlabbrev() .set(RdfProperties.RDF_rdfxml_tab, 3), .addLiteralTypes(true) .build();

Now when we rerun the sample code, we'll see the added root attribute on the root resource.

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:j="http://www.apache.org/juneau/" xmlns:jp="http://www.apache.org/juneaubp/" xmlns:per="http://www.apache.org/person/" xmlns:mail="http://www.apache.org/mail/" xmlns:addr="http://www.apache.org/address/"> <rdf:Description rdf:about="http://sample/addressBook/person/1"> <per:addressBookUri rdf:resource="http://sample/addressBook"/> <per:id rdf:datatype="http://www.w3.org/2001/XMLSchema#int">1</per:id> <per:name>John Smith</per:name> <per:addresses> <rdf:Seq> <rdf:li> <rdf:Description rdf:about="http://sample/addressBook/address/1"> <addr:personUri rdf:resource="http://sample/addressBook/person/1"/> <addr:id rdf:datatype="http://www.w3.org/2001/XMLSchema#int">1</addr:id> <mail:street>100 Main Street</mail:street> <mail:city>Anywhereville</mail:city> <mail:state>NY</mail:state> <mail:zip rdf:datatype="http://www.w3.org/2001/XMLSchema#int">12345</mail:zip> <addr:isCurrent rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</addr:isCurrent> </rdf:Description> </rdf:li> </rdf:Seq> </per:addresses> </rdf:Description> </rdf:RDF>

4 - juneau-dto

Maven Dependency

<dependency> <groupId>org.apache.juneau</groupId> <artifactId>juneau-dto</artifactId> <version>7.2.1</version> </dependency>

Java Library

juneau-dto-7.2.1.jar

OSGi Module

org.apache.juneau.dto_7.2.1.jar

The juneau-dto library contains several predefined POJOs for generating commonly-used document types. This section describes support for these POJOs.

4.1 - HTML5

The Juneau HTML5 DTOs are simply beans with fluent-style setters that allow you to quickly construct HTML fragments as Java objects. These object can then be serialized to HTML using one of the existing HTML serializers, or to other languages such as JSON using the JSON serializers.

The HtmlBuilder class is a utility class with predefined static methods that allow you to easily construct DTO instances in a minimal amount of code.

The following examples show how to create HTML tables.

Java code HTML
import static org.apache.juneau.dto.html5.HtmlBuilder.*; Object mytable = table( tr( th("c1"), th("c2") ), tr( td("v1"), td("v2") ) ); String html = HtmlSerializer.DEFAULT.serialize(mytable); <table> <tr> <th>c1</th> <th>c2</th> </tr> <tr> <td>v1</td> <td>v2</td> </tr> </table>
import static org.apache.juneau.dto.html5.HtmlBuilder.*; Object mydiv = div().align("center").onmouseover("alert(\"boo!\");") .children( p("Juneau supports ", b(i("mixed")), " content!") ); String html = HtmlSerializer.DEFAULT.serialize(mydiv); <div align='center' onmouseover='alert("boo!");'> <p>Juneau supports <b><i>mixed</i></b> content!</p> </table>
import static org.apache.juneau.dto.html5.HtmlBuilder.*; Object myform = form().action("/submit").method("POST") .children( "Position (1-10000): ", input("number").name("pos").value(1), br(), "Limit (1-10000): ", input("number").name("limit").value(100), br(), button("submit", "Submit"), button("reset", "Reset") ); String html = HtmlSerializer.DEFAULT.serialize(myform); <form action='/submit' method='POST'> Position (1-10000): <input name='pos' type='number' value='1'/><br/> Limit (1-10000): <input name='pos' type='number' value='100'/><br/> <button type='submit'>Submit</button> <button type='reset'>Reset</button> </form>

Using the HTML5 DTOs, you should be able to construct any valid HTML5 from full document bodies to any possible fragments.

The HtmlParser class can be used convert these HTML documents back into POJOs.

Other serializers and parsers (e.g. JsonSerializer) can be used to represent these POJOs in languages other than HTML.

Additional Information - org.apache.juneau.dto.html5
  1. Overview

    1. Generating HTML5

    2. Parsing HTML5

    3. HTML5 Templates

4.2 - Atom

The Juneau ATOM feed DTOs are simply beans with fluent-style setters.
The following code shows a feed being created programmatically using the AtomBuilder class.

import static org.apache.juneau.dto.atom.AtomBuilder.*; Feed feed = feed("tag:juneau.apache.org", "Juneau ATOM specification", "2016-01-02T03:04:05Z") .subtitle(text("html").text("Describes <em>stuff</em> about Juneau")) .links( link("alternate", "text/html", "http://juneau.apache.org").hreflang("en"), link("self", "application/atom+xml", "http://juneau.apache.org/feed.atom") ) .rights("Copyright (c) ...") .generator( generator("Juneau").uri("http://juneau.apache.org/").version("1.0") ) .entries( entry("tag:juneau.sample.com,2013:1.2345", "Juneau ATOM specification snapshot", "2016-01-02T03:04:05Z") .links( link"alternate", "text/html", "http://juneau.apache.org/juneau.atom"), link("enclosure", "audio/mpeg", "http://juneau.apache.org/audio/juneau_podcast.mp3").length(1337) ) .published("2016-01-02T03:04:05Z") .authors( person("Jane Smith").uri("http://juneau.apache.org/").email("janesmith@apache.org") ) .contributors( person("John Smith") ) .content( content("xhtml") .lang("en") .base("http://www.apache.org/") .text("<div><p><i>[Update: Juneau supports ATOM.]</i></p></div>") ) );

To serialize this to ATOM, use the XmlSerializer class:

Example with no namespaces

// Create a serializer with readable output, no namespaces yet. XmlSerializer s = XmlSerializer.create().sq().ws().build(); // Serialize to ATOM/XML String atomXml = s.serialize(feed);

Results

<feed> <id> tag:juneau.apache.org </id> <link href='http://juneau.apache.org/' rel='alternate' type='text/html' hreflang='en'/> <link href='http://juneau.apache.org/feed.atom' rel='self' type='application/atom+xml'/> <rights> Copyright (c) ... </rights> <title type='text'> Juneau ATOM specification </title> <updated>2016-01-02T03:04:05Z</updated> <generator uri='http://juneau.apache.org/' version='1.0'> Juneau </generator> <subtitle type='html'> Describes <em>stuff</em> about Juneau </subtitle> <entry> <author> <name>Jane Smith</name> <uri>http://juneau.apache.org/</uri> <email>janesmith@apache.org</email> </author> <contributor> <name>John Smith</name> </contributor> <id> tag:juneau.apache.org </id> <link href='http://juneau.apache.org/juneau.atom' rel='alternate' type='text/html'/> <link href='http://juneau.apache.org/audio/juneau_podcast.mp3' rel='enclosure' type='audio/mpeg' length='12345'/> <title> Juneau ATOM specification snapshot </title> <updated>2016-01-02T03:04:05Z</updated> <content base='http://www.apache.org/' lang='en' type='xhtml'> <div xmlns="http://www.w3.org/1999/xhtml" ><p><i>[Update: Juneau supports ATOM.]</i></p></div> </content> <published>2016-01-02T03:04:05Z</published> </entry> </feed>

The XmlParser class can be used convert these Atom documents back into POJOs.

Other serializers and parsers (e.g. JsonSerializer) can be used to represent these POJOs in languages other than XML.

Additional Information - org.apache.juneau.dto.atom
  1. Overview

    1. Serializing ATOM feeds

      1. ATOM/JSON

      2. ATOM/RDF/XML

      3. ATOM/HTML

    2. Parsing ATOM feeds

4.3 - Swagger

The Juneau Swagger DTOs are simply beans with fluent-style setters that allow you to quickly construct Swagger documents as Java objects.
These object can then be serialized to JSON using one of the existing JSON serializers, or to other languages such as XML or HTML using the other serializers.

The SwaggerBuilder class is a utility class with predefined static methods that allow you to easily construct DTO instances in a minimal amount of code.

The following is an example Swagger document from the Swagger website.

{ "swagger": "2.0", "info": { "title": "Swagger Petstore", "description": "This is a sample server Petstore server.", "version": "1.0.0", "termsOfService": "http://swagger.io/terms/", "contact": { "email": "apiteam@swagger.io" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "host": "petstore.swagger.io", "basePath": "/v2", "tags": [ { "name": "pet", "description": "Everything about your Pets", "externalDocs": { "description": "Find out more", "url": "http://swagger.io" } } ], "schemes": [ "http" ], "paths": { "/pet": { "post": { "tags": [ "pet" ], "summary": "Add a new pet to the store", "description": "", "operationId": "addPet", "consumes": [ "application/json", "text/xml" ], "produces": [ "application/json", "text/xml" ], "parameters": [ { "in": "body", "name": "body", "description": "Pet object that needs to be added to the store", "required": true } ], "responses": { "405": { "description": "Invalid input" } } } } } }

This document can be generated by the following Java code:

static import org.apache.juneau.dto.swagger.SwaggerBuilder.*; Swagger swagger = swagger() .swagger("2.0") .info( info("Swagger Petstore", "1.0.0") .description("This is a sample server Petstore server.") .termsOfService("http://swagger.io/terms/") .contact( contact().email("apiteam@swagger.io") ) .license( license("Apache 2.0").url("http://www.apache.org/licenses/LICENSE-2.0.html") ) ) .host("petstore.swagger.io") .basePath("/v2") .tags( tag("pet").description("Everything about your Pets") .externalDocs( externalDocumentation("http://swagger.io", "http://swagger.io") ) ) .schemes("http") .path("/pet", "post", operation() .tags("pet") .summary("Add a new pet to the store") .description("") .operationId("addPet") .consumes(MediaType.JSON, MediaType.XML) .produces(MediaType.JSON, MediaType.XML) .parameters( parameterInfo("body", "body") .description("Pet object that needs to be added to the store") .required(true) ) .response(405, responseInfo("Invalid input")) ); // Serialize using JSON serializer. String swaggerJson = JsonSerializer.DEFAULT_READABLE.serialize(swagger); // Or just use toString(). String swaggerJson = swagger.toString();

Methods that take in beans and collections of beans can also take in JSON representations of those objects.

// Pass in a JSON object representation of an Info object. swagger.info("{title:'Swagger Petstore',...}");

Properties can also be accessed via the SwaggerElement.get(String,Class) and SwaggerElement.set(String,Object) methods.
These methods can also be used to set and retrieve non-Swagger attributes such as "$ref" (which is not a part of the Swagger spec, but is part of the JSON Schema spec).

// Set a non-standard attribute. swagger.set("$ref", "http://foo.com"); // Retrieve a non-standard attribute. URI ref = swagger.get("$ref", URI.class);

Swagger docs can be parsed back into Swagger beans using the following code:

Swagger swagger = JsonParser.DEFAULT.parse(swaggerJson, Swagger.class);

4.4 - Swagger UI

The SwaggerUI class is a DTO class for generating Swagger user interfaces from Swagger beans.

The PetStore example described later provides an example of auto-generated Swagger JSON:

Using SwaggerUI, we're able to render that JSON as a Swagger user interface when the request is asking for HTML:

The class itself is nothing more than a POJO swap that swaps out Swagger beans with Div elements:

public class SwaggerUI extends PojoSwap<Swagger,Div> { @Override public MediaType[] forMediaTypes() { // Only use this swap when the Accept type is HTML. return new MediaType[] {MediaType.HTML}; } @Override public Div swap(BeanSession beanSession, Swagger swagger) throws Exception { ... } }

The BasicRestServlet class (describe later) shows how this swap is used in the REST interface to generate the Swagger UI shown above:

@RestResource( // Allow OPTIONS requests to be simulated using ?method=OPTIONS query parameter. allowedMethodParams="OPTIONS", // POJO swaps to apply to all serializers/parsers. pojoSwaps={ // Use the SwaggerUI swap when rendering Swagger beans. SwaggerUI.class }, ... ) public abstract class BasicRestServlet extends RestServlet implements BasicRestConfig { /** * [OPTIONS /*] - Show resource options. */ @RestMethod( name=OPTIONS, path="/*", summary="Swagger documentation", description="Swagger documentation for this resource.", htmldoc=@HtmlDoc( // Override the nav links for the swagger page. navlinks={ "back: servlet:/", "json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true" }, // Never show aside contents of page inherited from class. aside="NONE" ) ) public Swagger getOptions(RestRequest req) { // Localized Swagger for this resource is available through the RestRequest object. return req.getSwagger(); } }

5 - juneau-svl

Maven Dependency

<dependency> <groupId>org.apache.juneau</groupId> <artifactId>juneau-svl</artifactId> <version>7.2.1</version> </dependency>

Java Library

juneau-svl-7.2.1.jar

OSGi Module

org.apache.juneau.svl_7.2.1.jar

5.1 - Simple Variable Language

The juneau-svl module defines an API for a language called Simple Variable Language.
In a nutshell, Simple Variable Language (or SVL) is text that contains variables of the form "$varName{varKey}".
It is used extensively in the Config, REST and Microservice APIs.

Most variables can be recursively nested within the varKey (e.g. "$FOO{$BAR{xxx},$BAZ{xxx}}") and can return values that themselves contain more variables.

The VarResolver class is used to resolve variables.
The VarResolver.DEFAULT resolver is a reusable instance of this class configured with the following basic variables:

The following logic variables are also provided:

Example:

// Use the default variable resolver to resolve a string that contains $S (system property) variables String myProperty = VarResolver.DEFAULT.resolve("The Java home directory is $S{java.home}");

The following shows how variables can be arbitrarily nested...

// Look up a property in the following order: // 1) MYPROPERTY environment variable. // 2) 'my.property' system property if environment variable not found. // 3) 'not found' string if system property not found. String myproperty = VarResolver.DEFAULT.resolve("$E{MYPROPERTY,$S{my.property,not found}}");

5.2 - SVL Variables

Variables are defined through the Var API.
The API comes with several predefined variables and is easily extensible.

The following is an example of a variable that performs URL-Encoding on strings.

// First create our var. public class UrlEncodeVar extends SimpleVar { // Must have a no-arg constructor! public UrlEncodeVar() { super("UE"); } // The method we must implement @Override public String resolve(VarResolverSession session, String key) { return URLEncoder.encode(key, "UTF-8"); } } // Next create a var resolver that extends the existing DEFAULT resolver // that supports resolving system properties. VarResolver r = VarResolver.DEFAULT .builder() .vars(UrlEncodeVar.class) .build(); // Retrieve a system property and URL-encode it if necessary. String myProperty = r.resolve("$UE{$S{my.property}}");

The following shows the class hierarchy of the Var class:

  • Var - Superclass of all vars.
    • SimpleVar - Superclass of all vars that return strings.
      • DefaultingVar - Variables that define a default value if the resolve method returns null.
        • MapVar - Variables that pull values from maps.
      • MultipartVar - Variables that consist of 2 or more comma-delimited arguments.
    • StreamedVar - Superclass of all vars that stream their value to writers.

The following is the list of default variables defined in all modules:

ModuleClassPattern
juneau-svl EnvVariablesVar $E{key[,default]}
SystemPropertiesVar $S{key[,default]}
ArgsVar $A{key[,default]}
ManifestFileVar $MF{key[,default]}
IfVar $IF{arg,then[,else]}
SwitchVar $SW{arg,pattern1:then1[,pattern2:then2...]}
CoalesceVar $CO{arg1[,arg2...]}
PatternMatchVar $PM{arg,pattern}
NotEmptyVar $NE{arg}
UpperCaseVar $UC{arg}
LowerCaseVar $LC{arg}
juneau-config ConfigVar $C{key[,default]}
juneau-rest-server FileVar $F{path[,default]}}
ServletInitParamVar $I{name[,default]}
LocalizationVar $L{key[,args...]}
RequestAttributeVar $RA{key1[,key2...]}
RequestFormDataVar $RF{key1[,key2...]}
RequestHeaderVar $RH{key1[,key2...]}
RequestHeaderVar $RI{key}
RequestPathVar $RP{key1[,key2...]}
RequestQueryVar $RQ{key1[,key2...]}
RequestVar $R{key1[,key2...]}
SerializedRequestAttrVar $SA{contentType,key[,default]}
SwaggerVar $SS{key1[,key2...]}
UrlVar $U{uri}>
UrlEncodeVar $UE{uriPart}
WidgetVar $W{name}

5.3 - VarResolvers and VarResolverSessions

The main class for performing variable resolution is VarResolver.
Two methods are provided for resolving variables:

Var resolvers can rely on the existence of other objects.
For example, ConfigVar relies on the existence of a Config.
This is accomplished through the following:

  • Context-objects - Objects set on the resolver.
  • Session-objects - Objects set on the resolver session.

The following two classes are identical in behavior except for which objects they can access:

Context and session objects are set through the following methods:

Both kinds of objects are accessible through the following method:

Var resolvers can be cloned and extended by using the VarResolver.builder() method.
Cloning a resolver will copy it's Var class names and context objects.

Example:

// Create a resolver that copies the default resolver and adds $C and $A vars. VarResolver myVarResolver = VarResolver.DEFAULT .builder() .vars(ConfigVar.class, ArgsVar.class) .build();

5.4 - Other Notes

  • The escape character '\' can be used when necessary to escape the following characters: $ , { }
  • WARNING: It is possible to cause StackOverflowErrors if your nested variables result in a recursive loop (e.g. the environment variable 'MYPROPERTY' has the value '$E{MYPROPERTY}'). So don't do that!
  • As a general rule, this class tries to be as efficient as possible by not creating new strings when not needed.
    For example, calling the resolve method on a string that doesn't contain variables (e.g. resolver.resolve("foobar")) will simply be a no-op and return the same string.

6 - juneau-config

Maven Dependency

<dependency> <groupId>org.apache.juneau</groupId> <artifactId>juneau-config</artifactId> <version>7.2.1</version> </dependency>

Java Library

juneau-config-7.2.1.jar

OSGi Module

org.apache.juneau.config_7.2.1.jar

6.1 - Overview

The juneau-config library contains a powerful API for creating and using INI-style config files.

Example configuration file:

# A set of entries [Section1] # An integer key1 = 1 # A boolean key2 = true # An array key3 = 1,2,3 # A POJO key4 = http://bar

Config files are access through the Config class which are created through the ConfigBuilder class.
Builder creator methods are provided on the Config class:

// Create a Config object Config c = Config.create().name("MyConfig.cfg").build(); // Shortcut Config c = Config.create("MyConfig.cfg").build();

Once instantiated, reading values from the config are simple:

// Read values from section #1 int key1 = c.getInt("Section1/key1"); boolean key2 = c.getBoolean("Section1/key2"); int[] key3 = c.getObject("Section1/key3", int[].class); URL key4 = c.getObject("Section1/key4", URL.class);

The config language may look simple, but it is a very powerful feature with many capabilities including:

  • Support for storing and retrieving any of the following data types:
    • Primitives
    • POJOs
    • Beans
    • Arrays, Maps, and Collections of anything
    • Binary data
  • Transactional modifications with commit/rollback capabilities.
  • A listener API.
  • Filesystem watcher integration allowing changes on the file system to be reflected in real-time.
  • Modifications through the Config class (e.g. add/remove/modify sections and keys, add/remove comments and whitespace, etc...) DO NOT cause loss of formatting in the file.
    All existing whitespace and comments are preserved for you!
  • Value encoding for added security.
  • Support for SVL variables.
  • Directly populate beans from config sections.
  • Accessing config sections through Java interface proxies.
  • An extensible storage API allows you to write your own config storage (e.g. storage in databases or the cloud).

6.1.1 - Syntax Rules

  • Each config file contains zero or more sections containing zero or more entries:

    [Section1] key1 = 1 [Section2] key1 = 2

  • Unicode escapes can be used in values.

    key1 = \u0070\u0075\u0062\u006c\u0069\u0063

  • Comment lines start with the '#' character and can be placed on lines before sections and entries:

    # A comment about this section [Section1] # A comment about this entry key1 = 1

  • Comments can also be placed on the same line as entries:

    key1 = 1 # A comment about this entry

  • Values containing '#' must be escaped to prevent identification as a comment character:

    valueContainingPound = Value containing \u0023 character


    Likewise, '\' should be escaped to prevent confusion with unicode escapes.
  • Values containing newlines can span multiple lines.
    Subsequent lines start with a tab character.

    multiLineValue = line 1, line 2, line 3


    When retrieved, the above translates to "line1,\nline2,\nline3".
  • Leading and trailing whitespace on values are ignored.
  • Whitespace is not ignored within multi-line values (except for the leading tab character on each line).
  • Blank lines can be used anywhere in the file.

    # A comment line # Another comment line [Section1] ...

  • Values located before any sections are considered part of the no-name section, meaning they are accessed simply by key and not section/key.

    # Top of file # Use config.getString("key1") to retrieve. key1 = val1 # The first section [Section1] # Use config.getString("Section1/key2") to retrieve. key2 = val2

  • Section and key names must be at least one character long and not consist of any of the following characters:

    / \ [ ] = #

  • Whitespace in section and key names is technically allowed but discouraged.

6.2 - Entry Types

Configuration files can contain entries for anything from primitive types up to complex hierarchies of POJOs consisting of maps, collections, and/or beans.

6.2.1 - Primitive Types

The most common case for configuration values are primitives.

# A string key1 = foo # A boolean key2 = true # An integer key3 = 123 # A long key4 = 10000000000 # Doubles key5 = 6.67e−11 key6 = Infinity

The following methods are provided for accessing primitive values:

On integers and longs, "K", "M", and "G" can be used to identify kilo, mega, and giga.

key1 = 100K # Same as 1024000 key2 = 100M # Same as 104857600

Numbers can also use hexadecimal and octal notation:

hex1 = 0x12FE hex2 = 0X12FE octal1 = 01234

Strings with newlines are treated as multi-line values that get broken into separate lines:

key1 = This is a particularly long sentence that we want to split onto separate lines.

Typically, multi-line values are started on the next line for clarity like so:

key1 = This is a particularly long sentence that we want to split onto separate lines.

6.2.2 - POJOs

The following methods are provided for accessing POJO values:

In theory, any parsable POJO type can be represented as a config value.
However in practice, we're typically talking about the following:

  • Objects convertible from Strings.
  • Beans.

An example of an object convertible from a String was already shown in an example above.
In that case, it was a URL which has a public constructor that takes in a String:

# A POJO key4 = http://bar

// Read values from section #1 URL key4 = c.getObject("Section1/key4", URL.class);

Beans are represented as Simplified JSON by default:

// Contact information [ContactInfo] address = { street: '123 Main Street', city: 'Anywhere', state: 'NY', zip: 12345 }

// Example bean public class Address { public String street, city; public StateEnum state; public int zip; } // Example usage Config c = Config.create("MyConfig.cfg").build(); Address myAddress = c.getObject("ContactInfo/address", Address.class);

The format for beans depends on the serializer and parser registered on the Config which is defined in the builder via the following methods:

The default parser can also be overridden on the following getters:

6.2.3 - Arrays

The following methods are provided for accessing arrays:

The getStringArray() methods allow you to retrieve comma-delimited lists of values:

key1 = foo, bar, baz

String[] key1 = c.getStringArray("key1");

String arrays can also be represented in JSON when using the getObject() methods:

key1 = ['foo','bar','baz']

String[] key1 = c.getObject("key1", String.class);

Primitive arrays can also be retrieved using the getObject() methods:

key1 = [1,2,3]

int[] key1 = c.getObject("key1", int[].class);

Arrays of POJOs can also be retrieved using the getObject() methods:

addresses = [ { street: '123 Main Street', city: 'Anywhere', state: 'NY', zip: 12345 }, { street: '456 Main Street', city: 'Anywhere', state: 'NY', zip: 12345 } ]

Address[] addresses = c.getObject("addresses", Address[].class);

6.2.4 - Collections

The following methods are provided for accessing maps and collections:

The Type,Type... arguments allow you to specify the component types for maps and collections.
List class arguments can be followed by zero or one arguments representing the entry types.
Map class arguments can be followed by zero or two arguments representing the key and value types.
The arguments can be chained to produce any data structure consisting of maps, collections, or POJOs.


Examples are shown below:

  • getObject("...", List.class)
    Produces: List<?>
  • getObject("...", LinkedList.class)
    Produces: LinkedList<?>
  • getObject("...", HashSet.class, Integer.class)
    Produces: HashSet<Integer>
  • getObject("...", Map.class)
    Produces: Map<?,?>
  • getObject("...", HashMap.class)
    Produces: HashMap<?,?>
  • getObject("...", LinkedHashMap.class, String.class, MyBean.class)
    Produces: LinkedHashMap<String,MyBean>
  • getObject("...", HashMap.class, Integer.class, ArrayList.class, MyBean[].class)
    Produces: LinkedHashMap<Integer,ArrayList<MyBean[]>>
Example:

addresses = [ { street: '123 Main Street', city: 'Anywhere', state: 'NY', zip: 12345 }, { street: '456 Main Street', city: 'Anywhere', state: 'NY', zip: 12345 } ]

List<Address> addresses = c.getObject("addresses", ArrayList.class, Address.class);

Oftentimes, it might be useful to parse into the ObjectList and ObjectMap classes that provide the various convenience methods for working with JSON-like data structures:

ObjectMap m = c.getObject("key1", ObjectMap.class); ObjectList l = c.getObject("key2", ObjectList.class);

6.2.5 - Binary Data

The following methods are provided for accessing binary data:

Binary data can be represented in 3 formats:

  • BASE-64 (default)
    Example: "Zm9vYmFycw=="
  • Hexadecimal
    Example: "666F6F62617273"
  • Spaced hexadecimal
    Example: "66 6F 6F 62 61 72 73"

The binary data format is controlled via the following setting:

For example:

key = Zm9vYmFycw==

byte[] bytes = c.getBytes("key");

Binary lines can be split up into separate lines for readability:

key = Zm9vYm Fycw==

Binary data line wrapping can be controlled via the following setting:

6.3 - Variables

Config files can contain variables that get resolved dynamically using the previously-described VarResolver API.

Example:

#-------------------------- # My section #-------------------------- [MySection] # A system property locale = $S{java.locale, en_US} # An environment variable path = $E{PATH, unknown} # Another value in this config file anotherLocale = $C{MySection/locale} # Look for system property, or env var if that doesn't exist, or a default value if that doesn't exist. nested = $S{mySystemProperty,$E{MY_ENV_VAR,$C{MySection/anotherLocale}}} # A POJO with embedded variables aBean = {foo:'$S{foo}',baz:$C{MySection/anInt}}

Config c = Config.create().build(); Locale locale = cf.getObject("MySection/locale", Locale.class); String path = cf.getString("MySection/path"); int sameAsAnInt = cf.getInt("MySection/sameAsAnInt"); ABean bean = cf.getObject("MySection/aBean", ABean.class);

By default, Configs use the VarResolver.DEFAULT variable resolver which provides support for the following variables and constructs:

The variable resolver is controlled via the following setting:

Additionally, the following method can be used to retrieve a Config with a different variable resolver:

6.3.1 - Logic Variables

The default variable resolver also provides the following logic variables for performing simple logical operations:

The $IF variable can be used for simple if/else logic:

# Value set to 'foo' if myBooleanProperty is true key1 = $IF{ $S{myBooleanProperty}, foo } # Value set to 'foo' if myBooleanProperty is true, 'bar' if false. key2 = $IF{ $S{myBooleanProperty}, foo, bar } # Value set to key1 value if myBooleanProperty is true, key2 value if false. key3 = $IF{ $S{myBooleanProperty}, $C{key1}, $C{key2} }

The $SW variable can be used for switch blocks based on pattern matching:

# Shell command depends on the OS shellCommand = $SW{ $LC{$S{os.name}}, *win*: bat, linux: bash, *: sh }

The $CO variable can be used for coalescing of values (finding the first non-null/empty match):

# Debug flag can be enabled by system property or environment variable. debug = $CO{ $S{debug}, $E{DEBUG}, false }

The $PM variable can be used for calculating boolean values:

# Debug flag can be enabled by system property or environment variable. isWindows = $PM{ $LC{$S{os.name}}, *win* }

6.4 - Encoded Entries

Encoded entries allow for sensitive information such as passwords to be obfuscated.

Encoded entries are denoted with a '*' character at the end of the key name.

For example, the following password is marked for encoding:

[MyHost] url = http://localhost:9080/foo user = me password* = {AwwJVhwUQFZEMg==}

The default encoder is ConfigXorEncoder which is a simple XOR+Base64 encoder.

Custom encoders can be used to provide your own encoding support by implementing the ConfigEncoder interface.

Encoders are controlled via the following setting:

Encoded values can be set to plain-text values.
The curly brackets around the value identify whether the value has been encoded or not.

Unencoded values are encoded when the file is saved using the Config.commit() method.
They can also be encoded immediately by calling Config.encodeEntries().

6.5 - Section Maps

Config sections can be retrieved in-bulk using Config.getSectionAsMap(String).

Example:

// Example config file [MyAddress] street = 123 Main Street city = Anywhere state = NY zip = 12345

// Example usage Config c = Config.create("MyConfig.cfg").build(); ObjectMap m = c.getSectionAsMap("MyAddress"); String street = m.getString("street"); String city = m.getString("city"); String state = m.getString("state"); int zip = m.getInt("zip");

Maps created this way are snapshot copies of the section at the time of the method call.

6.6 - Section Beans

Config files can also be used to directly populate beans using Config.getSectionAsBean(String,Class,boolean).

Example:

// Example config file [MyAddress] street = 123 Main Street city = Anywhere state = NY zip = 12345

// Example bean public class Address { public String street, city; public StateEnum state; public int zip; } // Example usage Config c = Config.create("MyConfig.cfg").build(); Address myAddress = c.getSectionAsBean("MyAddress", Address.class);

Like maps, beans created this way are snapshot copies of the section at the time of the method call.

6.7 - Section Interfaces

Config sections can also be accessed via interface proxies using Config.getSectionAsInterface(String,Class).

While section maps and beans retrieve copies of the configuration data at the time of the method call, section interfaces can also be use to set values in the underlying configuration.

Example:

// Example config file [MySection] string = foo int = 123 enum = ONE bean = {foo:'bar',baz:123} int3dArray = [[[123,null],null],null] bean1d3dListMap = {key:[[[[{foo:'bar',baz:123}]]]]}

// Example interface. // Setters are optional. public interface MyConfigInterface { String getString(); void setString(String x); int getInt(); void setInt(int x); MyEnum getEnum(); void setEnum(MyEnum x); MyBean getBean(); void setBean(MyBean x); int[][][] getInt3dArray(); void setInt3dArray(int[][][] x); Map<String,List<MyBean[][][]>> getBean1d3dListMap(); void setBean1d3dListMap(Map<String,List<MyBean[][][]>> x); } // Example usage. Config c = Config.create("MyConfig.cfg").build(); MyConfigInterface ci = c.getSectionAsInterface("MySection", MyConfigInterface.class); // Read a value. int myInt = ci.getInt(); // Write a value. ci.setBean(new MyBean()); // Commit your changes to the store. c.commit();

6.8 - Setting Values

The following methods allow you to add, remove, and modify entries and sections in a config file:

// Construct the sample config file programmatically Config c = Config.create("MyConfig.cfg").build() .set("key1", 1) .set("key2", true) .set("key3", new int[]{1,2,3}) .set("key4", new URI("http://foo")) .set("Section1/key1", 2) .set("Section1/key2", false) .set("Section1/key3", new int[]{4,5,6}) .set("Section1/key4", new URI("http://bar")) .commit();

The method Config.set(String,Object,Serializer,ConfigMod[],String,List) can be used for adding comments and pre-lines to entries, and specifying encoded values.

// Set an encoded value with some comments. c.set("key1", 1, null, ConfigMod.ENCODED, "Same-line comment", Arrays.asList( "# Comment 1", "", "# Comment 2" ) );

# Comment 1 # Comment 2 key1 = 1 # Same-line comment

The last 4 arguments in Config.set(String,Object,Serializer,ConfigMod[],String,List) are optional in that if you pass null, the current value will not be overwritten.
To unset the same-line comment, you should pass in a blank string.
To remove pre-lines, you should pass in an empty list.

Sections can be added with optional pre-lines using the setSection methods:

// Set an encoded value with some comments. c.setSection("NewSection", Arrays.asList( "# Section comment 1", "", "# Section comment 2" ) );

# Section comment 1 # Section comment 2 [NewSection]

Changes made to the configuration are transactional in nature.
They are kept in memory until you call the Config.commit() method.
Until then, you still see the modified values when you call any of the getters, but the modified values exist only in memory.

Changes can be rolled back using the Config.rollback() method.

6.8.1 - File System Changes

In general, external file modifications will be detected immediately in the Config object when a watcher thread is enabled (explained later).
Otherwise, they are detected when a commit is performed.

The Config object maintains an in-memory record of all changes that have been applied to it through getters and setters.
When the underlying file changes, the new contents are loaded and the in-memory changes are then applied to the new configuration.
This provides the benefits of real-time updates of configurations while not losing any changes made in the JVM.

If the commit() method is called on the Config objects after the file system contents have been modified, we will then reload the configuration from the file system, apply the changes, and then try to save to the file system again (up to 10 times).

If the same entry is both internally and externally modified, the external modification will be overwritten (although both change events will be seen by listeners).

6.8.2 - Custom Entry Serialization

Setter methods that take in a Serializer can be used to provide custom serialization of entries instead of using the predefined serializer.

// Set an XML value instead of JSON. c.set("key1", myAddress, XmlSerializer.DEFAULT_SQ_READABLE);

key1 = <address> <street>123 Main Street</street> <city>Anywhere</city> <state>NY</state> <zip>12345</zip> </address>

The value can then be retrieved using the equivalent parser:

Address myAddress = c.getObject("key1", XmlParser.DEFAULT, Address.class);

6.8.3 - Setting Values in Bulk

The following methods can be used to bulk-load configuration values:

Changes can then be committed using the Config.commit() method.

6.9 - Listeners

Configuration change events can be listened for using the following methods:

The ConfigEventListener interface consists of the following method:

The ConfigEvent class provides access to all the information about the updated entry:

The listener method is triggered:

  • After Config.commit() is called.
  • When the file changes on the file system.

In both cases, the listener is triggered after the changes have been committed.

final Config c = Config.create("MyConfig.cfg").build(); // Add a listener for changes to MySection/key1 c.addListener( new ConfigEventListener() { @Override public void onConfigChange(List<ConfigEvent> events) { for (ConfigEvent event : events) { if (event.getType() == SET_ENTRY) { String section = event.getSection(); String key = event.getKey(); if (section.equals("MySection") && key.equals("key1")) { // Get the new value from the event. String newVal = event.getValue(); // Or get the new value from the config (since the change has already been committed). newVal = c.getString("MySection/key1"); } } } } } )

6.10 - Serializing

The following methods are used for serializing Config objects back into INI files:

Both methods are thread safe.

The Config class implements the Writable which means it can be returned as-is by REST methods to be serialized as INI text.

6.11 - Config Stores

Configuration files are stored in entities called Stores.

The methods that need to be implemented on a store are:

Read is self-explanatory:

public String read(String name) { // Return the contents of the specified configuration. }

Write is slightly trickier:

public String write(String name, String oldContents, String newContents) { // If the old contents match the current stored contents, the new contents will get stored, // and the method returns null indicating success. // If the old contents DO NOT match the current stored contents (i.e. it was modified in some way), // the new contents are NOT stored, and the method returns the current stored contents. // If the old contents are null, then just always write the new contents. }

The update method is called whenever the stored file gets modified externally:

public String update(String name, String newContents) { // Do something with the updated contents. }

Two configuration stores are provided by default:

The store is defined on the Config object via the following setting:

Example:

// Create a config with in-memory storage. Config c = Config.create("MyConfig.cfg").store(ConfigMemoryStore.DEFAULT).build();

The default store used is ConfigFileStore.DEFAULT which defines the execution directory as the file system directory to store and retrieve files.

6.11.1 - ConfigMemoryStore

The ConfigMemoryStore class is simply an in-memory storage location for configuration files.
There is no hard persistence and is used primarily for testing purposes.

However, the implementation provides a good idea on how stores work (especially the write method):

public class ConfigMemoryStore extends ConfigStore { // Some methods ommitted. private final ConcurrentHashMap<String,String> cache = new ConcurrentHashMap<>(); @Override /* ConfigStore */ public synchronized String read(String name) { return emptyIfNull(cache.get(name)); } @Override /* ConfigStore */ public synchronized String write(String name, String expectedContents, String newContents) { // This is a no-op. if (isEquals(expectedContents, newContents)) return null; String currentContents = read(name); if (expectedContents != null && ! isEquals(currentContents, expectedContents)) return currentContents; update(name, newContents); // Success! return null; } @Override /* ConfigStore */ public synchronized ConfigMemoryStore update(String name, String newContents) { cache.put(name, newContents); super.update(name, newContents); // Trigger any listeners. return this; } }

6.11.2 - ConfigFileStore

The ConfigFileStore is the typical store used for configuration files. It provides the following configurable settings:

Example:

// Create a config store with a watcher thread and high sensitivity. ConfigFileStore fs = ConfigFileStore.create().directory("configs").useWatcher().watcherSensitivity(HIGH).build(); // Create a config using the store defined above. Config c = Config.create("MyConfig.cfg").store(fs).build();

6.11.3 - Custom ConfigStores

The ConfigStore API has been written to allow easy development of custom configuration storage classes.

The example below shows a starting point for an implementation based on polling a relational database.
Completing it is left as an exercise:

Example Store Class:

public class ConfigSqlStore extends ConfigStore { // Configurable properties static final String CONFIGSQLSTORE_jdbcUrl = "ConfigSqlStore.jdbcUrl.s", CONFIGSQLSTORE_tableName = "ConfigSqlStore.tableName.s", CONFIGSQLSTORE_nameColumn = "ConfigSqlStore.nameColumn.s", CONFIGSQLSTORE_valueColumn = "ConfigSqlStore.valueColumn.s", CONFIGSQLSTORE_pollInterval = "ConfigSqlStore.pollInterval.i"; // Instance fields private final String jdbcUrl; private final String tableName, nameColumn, valueColumn; private final Timer watcher; private final ConcurrentHashMap<String,String> cache = new ConcurrentHashMap<>(); // Constructor called from builder. protected ConfigSqlStore(PropertyStore ps) { super(ps); this.jdbcUrl = getStringProperty(CONFIGSQLSTORE_jdbcUrl, "jdbc:derby:mydb"); this.tableName = getStringProperty(CONFIGSQLSTORE_tableName); this.nameColumn = getStringProperty(CONFIGSQLSTORE_nameColumn); this.valueColumn = getStringProperty(CONFIGSQLSTORE_valueColumn); int pollInterval = getStringProperty(CONFIGSQLSTORE_pollInterval, 600); TimerTask timerTask = new TimerTask() { @Override public void run() { ConfigSqlStore.this.poll(); } }; this.watcher = new Timer("MyTimer"); watcher.scheduleAtFixedRate(timerTask, 0, pollInterval * 10000); } private synchronized void poll() { // Loop through all our entries and find the latest values. for (Map.Entry<String,String> e : cache.entrySet()) { String name = e.getKey(); String cacheContents = e.getValue(); String newContents = getDatabaseValue(name); // Change detected! if (! cacheContents.equals(newContents)) update(name, newContents); } } // Reads the value from the database. protected String getDatabaseValue(String name) { // Implement me! } @Override /* ConfigStore */ public synchronized String read(String name) { String contents = cache.get(name); if (contents == null) { contents = getDatabaseValue(name); update(name, contents); } return contents; } @Override /* ConfigStore */ public synchronized String write(String name, String expectedContents, String newContents) { // This is a no-op. if (isEquals(expectedContents, newContents)) return null; String currentContents = read(name); if (expectedContents != null && ! isEquals(currentContents, expectedContents)) return currentContents; update(name, newContents); // Success! return null; } @Override /* ConfigStore */ public synchronized ConfigSqlStore update(String name, String newContents) { cache.put(name, newContents); super.update(name, newContents); // Trigger any listeners. return this; } @Override /* Closeable */ public synchronized void close() { if (watcher != null) watcher.cancel(); } }

The purpose of the builder class is to simply set values in the PropertyStore that's passed to the ConfigStore:

Example Builder Class:

public class ConfigSqlStoreBuilder extends ConfigStoreBuilder { public ConfigSqlStoreBuilder() { super(); } public ConfigSqlStoreBuilder(PropertyStore ps) { super(ps); } public ConfigSqlStoreBuilder jdbcUrl(String value) { super.set(CONFIGSQLSTORE_jdbcUrl, value); return this; } public ConfigSqlStoreBuilder tableName(String value) { super.set(CONFIGSQLSTORE_tableName, value); return this; } public ConfigSqlStoreBuilder nameColumn(String value) { super.set(CONFIGSQLSTORE_nameColumn, value); return this; } public ConfigSqlStoreBuilder valueColumn(String value) { super.set(CONFIGSQLSTORE_valueColumn, value); return this; } public ConfigSqlStoreBuilder pollInterval(int value) { super.set(CONFIGSQLSTORE_pollInterval, value); return this; } @Override /* ContextBuilder */ public ConfigFileStore build() { return new ConfigFileStore(getPropertyStore()); } }

6.11.4 - ConfigStore Listeners

The ConfigStore class has the following listener methods:

Note that this is a different listener than ConfigEventListener.
In this case, we're just listening for changed files:

This listener is used by the Config class to listen for changes on the file system so that it can be updated in real-time.

6.12 - Read-only Configs

The following settings can be used to create read-only Config objects:

Example:

// Create a read-only config Config c = Config.create("MyConfig.cfg").readOnly().build();

This causes all methods that make modifications to throw UnsupportedOperationException.

6.13 - Closing Configs

In general, it's good practice to close Config if you're only creating them temporarily so that their listeners get unregistered from the underlying storage APIs.

Example:

// Create a transient config. Config c = Config.create("MyConfig.cfg").build(); // Do stuff with it. // Then close the config to unregister the listeners. c.close();

7 - juneau-rest-server

Maven Dependency

<dependency> <groupId>org.apache.juneau</groupId> <artifactId>juneau-rest-server</artifactId> <version>7.2.1</version> </dependency>

Java Library

juneau-rest-server-7.2.1.jar

OSGi Module

org.apache.juneau.rest.server_7.2.1.jar

The juneau-rest-server library allows you to quickly wrap POJOs and expose them as full-fledged REST resources served up in a servlet container using a bare-minimum amount of code.
The primary goal for Juneau was to make it as easy as possible to implement easy-to-read and self-documenting REST resources using very little code.

One of the biggest advantages of the Juneau REST framework over similar architectures is that it hides the serialization layer from the developer.
The developer can work entirely with POJOs and let the Juneau framework handle all the serialization and parsing work.
The developer need never know what the Accept or Content-Type or Accept-Encoding (etc...) header values are because those details are all handled by the framework.

The API builds upon the existing JEE Servlet API.
The root class, RestServlet is nothing but a specialized HttpServlet, and the RestRequest and RestResponse classes are nothing more than specialized HttpServletRequest and HttpServletResponse objects.
This allows maximum flexibility for the developer since you can let Juneau handle operations such as serialization, or you can revert to the existing servlet APIs to do low-level processing of requests yourself.
It also means you need nothing more than a Servlet container such as Jetty to use the REST framework.

Features
  • Serializes POJOs to JSON, XML, HTML, URL-Encoding, UON, RDF/XML, N-Triple, Turtle, N3, SOAP, or Java-serialized-object based on value of Accept header.
    No user code is required to handle these types.
    • Extensible design that provides ability to override existing content type handlers, or add the ability to handle other kinds of content types.
  • Parses content of POST/PUT request bodies to POJOs.
  • Automatic built-in ability to serialize POJO metadata to JSON+SCHEMA, XML+SCHEMA, or HTML+SCHEMA based on Accept header.
  • Automatic negotiation of output Writer based on HTTP headers.
    • Automatic handling of Accept-Charset header for all character sets supported by the JVM.
    • Automatic handling of Accept-Encoding header with registered encoders.
  • Automatic error handling.
    • Automatic 401 errors (Unauthorized) on failed guards.
    • Automatic 404 errors (Not Found) on unmatched path patterns.
    • Automatic 405 errors (Method Not Implemented) on unimplemented methods.
    • Automatic 406 errors (Not Acceptable) when no matching serializer was found to handle the Accept header.
    • Automatic 412 errors (Precondition Failed) when all matchers failed to match.
    • Automatic 415 errors (Unsupported Media Type) when no matching parser was found was found to handle the Content-Type header.
    • Automatic 500 errors on uncaught exceptions.
  • Support for parsing all HTTP parts (headers, query, formData, path variables) using Swagger formatting rules and validations.
    Not limited to simple POJOs, but rather you can represent arbitrarily-complex POJOs in any HTTP part using UON notation.
  • Auto-created Swagger JSON and Swagger UI available through OPTIONS requests of resources.
  • Various useful debugging features that make debugging using a browser extremely simple...
    • Ability to pass HTTP header values as URL GET parameters (e.g. &Accept=text/xml).
    • Ability to pass HTTP content on PUT/POST requests as a URL GET parameter (e.g. &content=(foo=bar)).
    • Ability to simulate non-GET requests using a &method GET parameter (e.g. &method=POST).
    • Ability to force "text/plain" on response using GET parameter &plainText=true.
  • Ability to implement overloaded HTTP methods through the use of the &method attribute (e.g. &method=FOO).
  • Ability to match URL patterns (e.g. /foo/{fooId}/bar/{barId}) against URLs (e.g. /foo/123/bar/456/bing).
  • Ability to associate guards at the resource or method levels through annotations.
    Typically useful for security, but can be used for a variety of purposes.
  • Ability to associate converters at the resource or method levels through annotations.
    Typically useful for performing conversions on input and output, such as for supporting older input and output formats.

Many of the examples in this document are pulled directly from juneau-examples-rest.

7.1 - Hello World Example

A REST resource is simply a Java class annotated with RestResource.
The most common case is a class that extends RestServlet, which itself is simply an extension of HttpServlet which allows it to be deployed as a servlet.

In this example, we define a resource called HelloWorldResource.
This example is located in the juneau-examples-rest project.
It's assumed the reader is familiar with defining servlets in web applications.

Like any servlet, we could define our resource in the web.xml file of the web application like so...

<?xml version="1.0" encoding="UTF-8"?> <web-app version="2.3"> <servlet> <servlet-name>HelloWorldResource</servlet-name> <servlet-class>com.foo.sample.HelloWorldResource</servlet-class> </servlet> <servlet-mapping> <servlet-name>HelloWorldResource</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> </web-app>

Our servlet code is shown below:

// Sample REST resource that prints out a simple "Hello world!" message. @RestResource( path="/helloWorld", title="Hello World", description="An example of the simplest-possible resource", htmldoc=@HtmlDoc( navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS" }, aside={ "<div style='max-width:400px' class='text'>", " <p>This page shows a resource that simply response with a 'Hello world!' message</p>", " <p>The POJO serialized is a simple String.</p>", "</div>" } ) ) public class HelloWorldResource extends BasicRestServlet { @RestMethod(name=GET, path="/*", summary="Responds with \"Hello world!\"") public String sayHello() { return "Hello world!"; } }

This is what it looks like in a browser:

http://localhost:10000/helloWorld

It doesn't much simpler than that.
In this case, we're simply returning a string that will be converted to any of the supported languages (e.g. JSON, XML, HTML, ...).
However, we could have returned any POJO consisting of beans, maps, collections, etc...

The BasicRestServlet class that we're using here is a subclass of RestServlet that provides default support for a variety of content types.
Implementers can choose to use this class, or create their own subclass of RestServlet with their own specialized serializers and parsers.

7.2 - Class Hierarchy

The class hierarchy for the REST servlet class is shown below:

The servlets with RDF support require Jena on the classpath.
All other serializers and parsers do not have any external library dependencies.
For this reason, we have separate servlets for supporting RDF so that you don't need Jena if you don't need to support RDF.

Everything is configured through the following classes which you will see a lot:

7.3 - Instantiation

REST resources are deployed in one of two ways:

  • Deployed in a J2EE container as a servlet.
  • Deployed as a child of another REST resource.

When deployed in a J2EE container, you MUST extend from one of the servlet classes.

When deployed as a child of another resource, you MAY extend from one of the servlet classes but it's not necessary.
The only requirement is that the class be annotated with @RestResource and have one of the following constructors:

  • public T()
  • public T(RestContextBuilder)

And even that requirement is relaxed if you implement your own REST resource resolver (described later).

For example:

// Top level resource is deployed like any other servlet and must subclass from RestServlet. @RestResource( path="/top", children={ ChildResource.class // Accessed via URI "/top/child" } ) public class TopLevelResource extends BasicRestServlet {...}

// Child resources can inherit from RestServlet but it's not a requirement. @RestResource( path="/child" ) public class ChildResource extends WhateverYouWant {...}

That's all there is to it! There's no code scanning, module configuration/initialization classes, or anything complex like that. It's just a servlet.

7.3.1 - RestServlet

The RestServlet class is the entry point for your REST resources.
It extends directly from HttpServlet and is deployed like any other servlet.

When the servlet init() method is called, it triggers the code to find and process the @RestResource annotations on that class and all child classes.
These get constructed into a RestContext object that holds all the configuration information about your resource in a read-only object.

Most developers are not going to be using the RestServlet class itself, and instead will extend from one of the preconfigured default servlets such as BasicRestServlet.
The RestServlet class by itself is not configured with any serializers and parsers, and therefore not very useful on it's own. However, the class does provide a couple of convenience methods to be aware of:

7.3.2 - BasicRestServlet

The BasicRestServlet class is a subclass of RestServlet preconfigured with the following:

  • A default set of serializers and parsers (pretty much all of them except for the RDF ones).
  • Some basic HTML boilerplate for the HTML representation of your POJOs.
  • Support for auto-generated Swagger documentation through OPTIONS page requests.
  • Configuration of default CSS stylesheets.
  • Default contents for HTML views.

The contents of the class is shown below.
You should notice that very little code is being used and everything is configurable through annotations:

@RestResource( // Allow OPTIONS requests to be simulated using ?method=OPTIONS query parameter. allowedMethodParams="OPTIONS", // HTML-page specific settings. htmldoc=@HtmlDoc( // Basic page navigation links. navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS" } ) ) public abstract class BasicRestServlet extends RestServlet implements BasicRestConfig { /** * [OPTIONS /*] - Show resource options. * * @param req The HTTP request. * @return A bean containing the contents for the OPTIONS page. */ @RestMethod(name=OPTIONS, path="/*", summary="Swagger documentation", description="Swagger documentation for this resource.", htmldoc=@HtmlDoc( // Override the nav links for the swagger page. navlinks={ "back: servlet:/", "json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true" }, // Never show aside contents of page inherited from class. aside="NONE" ), // POJO swaps to apply to all serializers/parsers. pojoSwaps={ // Use the SwaggerUI swap when rendering Swagger beans. SwaggerUI.class }, // Properties to apply to all serializers/parsers and REST-specific API objects. properties={ // Add descriptions to the following types when not specified: @Property(name=JSONSCHEMA_addDescriptionsTo, value="bean,collection,array,map,enum"), // Automatically add examples to the following types: @Property(name=JSONSCHEMA_addExamplesTo, value="bean,collection,array,map"), // Don't generate schema information on the Swagger bean itself or HTML beans. @Property(name=JSONSCHEMA_ignoreTypes, value="Swagger,org.apache.juneau.dto.html5.*") }, // Shortcut for boolean properties. flags={ // Use $ref references for bean definitions to reduce duplication in Swagger. JSONSCHEMA_useBeanDefs } ) public Swagger getOptions(RestRequest req) { // Localized Swagger for this resource is available through the RestRequest object. return req.getSwagger(); } }

Additional annotations are pulled in from the BasicRestConfig interface which simply exists to define a common set of annotations. Notice that it has no code at all.

@RestResource( // Default serializers for all Java methods in the class. serializers={ HtmlDocSerializer.class, HtmlStrippedDocSerializer.class, HtmlSchemaDocSerializer.class, JsonSerializer.class, JsonSerializer.Simple.class, JsonSchemaSerializer.class, XmlDocSerializer.class, XmlSchemaDocSerializer.class, UonSerializer.class, UrlEncodingSerializer.class, MsgPackSerializer.class, SoapXmlSerializer.class, PlainTextSerializer.class }, // Default parsers for all Java methods in the class. parsers={ JsonParser.class, JsonParser.Simple.class, XmlParser.class, HtmlParser.class, UonParser.class, UrlEncodingParser.class, MsgPackParser.class, PlainTextParser.class }, // Properties to apply to all serializers/parsers and REST-specific API objects. properties={ // Enable automatic resolution of URI objects to root-relative values. @Property(name=SERIALIZER_uriResolution, value="ROOT_RELATIVE") }, // HTML-page specific settings htmldoc=@HtmlDoc( // Default page header contents. header={ "<h1>$R{resourceTitle}</h1>", // Use @RestResource(title) "<h2>$R{methodSummary,resourceDescription}</h2>", // Use either @RestMethod(summary) or @RestResource(description) "$C{REST/header}" // Extra header HTML defined in external config file. }, // Basic page navigation links. navlinks={ "up: request:/.." }, // 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). stylesheet="$C{REST/theme,servlet:/htdocs/themes/devops.css}", // Default contents to add to the <head> section of the HTML page. // Use it to add a favicon link to the page. head={ "<link rel='icon' href='$U{$C{REST/favicon}}'/>" }, // No default page footer contents. // Can be overridden from external config file. footer="$C{REST/footer}", // By default, table cell contents should not wrap. nowrap="true" ), // Optional external configuration file. config="$S{juneau.configFile}", // 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. staticFiles={"$C{REST/staticFiles}"} ) public interface BasicRestConfig {}

Your top-level resource will simply extend from this class, as shown in the Hello World example from a couple sections back.

It's important to notice that the @RestResource annotation is inheritable and overridable from parent class and interfaces. They'll all get merged into a single set of annotation values for the resource class.

Not shown but equally important is that all of the annotations shown have programmatic equivalents via the RestContextBuilder class which can be manipulated during servlet initialization.
(As a general rule, all annotations throughout Juneau have programmatic equivalents.)

There's a lot going on in this class.
But not to worry, the details will be described later.

7.3.3 - Children

Child Resources are REST servlets or objects that are linked to parent resources through the @RestResource(children) annotation.

Example:

/** Parent Resource */ @RestResource( path="/parent", children={FooResource.class} ) public MyResource extends BasicRestServlet {...}

/** Child Resource */ @RestResource( path="/foo" // Path relative to parent resource. ) public FooResource {...} // Note that we don't need to extend from RestServlet.

The path of the child resource gets appended to the path of the parent resource.
So in the example above, the child resource is accessed through the URL /parent/foo.

A HUGE advantage of using child resources is that they do not need to be declared in the JEE web.xml file.
Initialization of and access to the child resources occurs through the parent resource.
Children can be nested arbitrary deep to create complex REST interfaces with a single top-level REST servlet.

See Also:

7.3.4 - Router Pages

The BasicRestServletGroup class provides a default "router" page for child resources when a parent resource is nothing more than a grouping of child resources.

The RootResources class in the Samples project is an example of a router page:

/** * Sample REST resource showing how to implement a "router" resource page. */ @RestResource( path="/", title="Root resources", description="Example of a router resource page.", children={ HelloWorldResource.class, PetStoreResource.class, PhotosResource.class, DtoExamples.class, SqlQueryResource.class, ConfigResource.class, LogsResource.class, DebugResource.class, ShutdownResource.class } ) public class RootResources extends BasicRestServletGroup { // NO CODE!!! }

When you bring up this resource in a browser, you see the following that provides a list of navigable links to your child resources:

http://localhost:10000

The BasicRestServletGroup class is nothing more than a subclass of BasicRestServlet with a getChildren() method mapped to the servlet root path.
The method returns a POJO with is just a linked-list of beans with name/description properties.

// The entire contents of the BasicRestServletGroup class. public class BasicRestServletGroup extends BasicRestServlet { @RestMethod(name=GET, path="/", description="Child resources") public ChildResourceDescriptions getChildren(RestRequest req) { return new ChildResourceDescriptions(this, req); } }

7.3.5 - Resource Resolvers

By default, you can add the @RestResource to any class as long as it has one of the following constructors:

  • public T()
  • public T(RestContextBuilder)

The latter constructor can be used to get access to the RestContextBuilder object to make any configurations to the resource before it's initialized.

Resource object resolution is controlled through the following API:

This API can be extended to provide your own custom resource resolution.
Later topics discuss how to use this API to instantiate resources using Spring.

See Also:

7.3.6 - Lifecycle Hooks

Lifecycle hooks allow you to hook into lifecycle events of the servlet/resource creation and REST calls.

For example, if you want to add an initialization method to your resource:

@RestResource(...) public class MyResource { // Our database. private Map<Integer,Object> myDatabase; @RestHook(INIT) public void initMyDatabase(RestContextBuilder builder) throws Exception { myDatabase = new LinkedHashMap<>(); } }

Or if you want to intercept REST calls:

@RestResource(...) public class MyResource { // Add a request attribute to all incoming requests. @RestHook(PRE_CALL) public void onPreCall(RestRequest req) { req.setAttribute("foo", "bar"); } }

The hook events can be broken down into two categories:

  • Resource lifecycle events:
  • REST call lifecycle events:
    • START_CALL - At the beginning of a REST call.
    • PRE_CALL - Right before the @RestMethod method is invoked.
    • POST_CALL - Right after the @RestMethod method is invoked.
    • END_CALL - At the end of the REST call after the response has been flushed.
See Also:

7.4 - @RestResource

The @RestResource annotation is the primary way of defining and configuring REST resource classes.
The functionality of the class itself is covered in detail in the topics below.

7.4.1 - Annotation Inheritance

The @RestResource annotation can also be used on parents and interfaces of resource classes.
When multiple annotations are defined at different levels, the annotation values are combined.

This is a particularly useful feature because it allows you to define your own configured parent resource classes that can be extended by all your child resources so that they all share common settings.

Inheritance rules
Annotation Inheritence Rules
guards() Guards on child are combined with those on parent class.
Guards are executed child-to-parent in the order they appear in the annotation.
Guards on methods are executed before those on classes.
converters() Converters on child are combined with those on parent class.
Converters are executed child-to-parent in the order they appear in the annotation.
Converters on methods are executed before those on classes.
beanFilters() Bean filters on child override those on parent class.
Inherit class can be used to inherit and augment values from parent.
None class can be used to suppress inheriting from parent.
pojoSwaps() POJO swaps on child override those on parent class.
Inherit class can be used to inherit and augment values from parent.
None class can be used to suppress inheriting from parent.
properties() Properties on child are combined with those on parent class.
Properties are applied parent-to-child in the order they appear in the annotation.
Properties on methods take precedence over those on classes.
serializers() Serializers on child override those on parent class.
Inherit class can be used to inherit and augment values from parent.
None class can be used to suppress inheriting from parent.
Serializers on methods take precedence over those on classes.
parsers() Parsers on child override those on parent class.
Inherit class can be used to inherit and augment values from parent.
None class can be used to suppress inheriting from parent.
Parsers on methods take precedence over those on classes.
responseHandlers() Response handlers on child are combined with those on parent class.
encoders() Encoders on child are combined with those on parent class.
defaultRequestHeaders() Headers on child are combined with those on parent class.
Headers are applied parent-to-child in the order they appear in the annotation.
Headers on methods take precedence over those on classes.
defaultResponseHeaders() Headers on child are combined with those on parent class.
Headers are applied parent-to-child in the order they appear in the annotation.
children() Children on child are combined with those on parent class.
Children are list parent-to-child in the order they appear in the annotation.
path() Path is searched for in child-to-parent order.
title() Label is searched for in child-to-parent order.
description() Description is searched for in child-to-parent order.
config() Config file is searched for in child-to-parent order.
staticFiles() Static files on child are combined with those on parent class.
Static files are are executed child-to-parent in the order they appear in the annotation.

7.5 - RestContext

The RestContext object is the workhorse class for all of the configuration of a single REST resource class.
It's by-far the most important class in the REST API.

Every class annotated with @RestResource ends up with an instance of this object.
The object itself is read-only and unchangeable.
It is populated through the following:

The annotation should be self-explanatory at this point.
The builder allows you to perform all of the same configuration as the annotation programmatically.

The RestContextBuilder class extends BeanContextBuilder allowing you to programmatically set any properties defined on that builder class.
It also implements ServletConfig

To access this object, simply pass it in as a constructor argument or in an INIT hook:

// Option #1 - Pass in through constructor. public MyResource(RestContextBuilder builder) { builder .pojoSwaps(CalendarSwap.RFC2822DTZ.class) .set(PARSER_debug, true); } // Option #2 - Use an INIT hook. @RestHook(INIT) public void init(RestContextBuilder builder) throws Exception { builder .pojoSwaps(CalendarSwap.RFC2822DTZ.class) .set(PARSER_debug, true); }

Warning: The builder class is huge. Through it, you can configure bean/serializer/parser settings, define config files, children, resource finders, info providers, etc...

7.6 - @RestMethod

REST Java methods are identified on REST servlets using the @RestMethod annotation.
The annotation allows the framework to identify the available REST methods through reflection.

Example:

@RestMethod(name=GET, path="/") public String sayHello() { return "Hello world!"; }

When the name and/or path values are not specified, their values are inferred from the Java method name.

The HTTP method can be inferred from the Java method by starting the method name with any of the following:

  • get
  • put
  • post
  • delete
  • options
  • head
  • trace
  • patch

If path is not defined, it's inferred from the Java method name (minus the prefix above).

Examples:

// Method="GET", path="/foo" @RestMethod public String getFoo() {...}

// Method="DELETE", path="/foo" @RestMethod public String deleteFoo() {...}

// Method="GET", path="/foo" // "GET" is default @RestMethod public String foo() {...}

// Method="GET", path="/" @RestMethod(path="/") public String foo() {...}

// Method="GET", path="/" @RestMethod public String get() {...}

// Method="POST", path="/" @RestMethod public String post() {...}

If name and path are both specified, the Java method name can be anything.

7.6.1 - Java Method Parameters

Java methods can contain any of the following parameters in any order:

Example:

@RestMethod(name=GET, path="/example1/{a1}/{a2}/{a3}/*") public String doGetExample1( RestRequest req, RestResponse res, @Method String method, @Path("a1") String a1, @Path("a2") int a2, @Path("a3") UUID a3, @Query("p1") int p1, @Query("p2") String p2, @Query("p3") UUID p3, @HasQuery("p3") boolean hasP3, @Path("/*") String remainder, @Header("Accept-Language") String lang, @Header("Accept") String accept, @Header("DNT") int doNotTrack, RequestProperties properties, ResourceBundle nls ) { // Do something with all of those }

Notes:
  • All annotations have programmatic equivalents on the RestRequest class.
See Also:

7.6.2 - RestRequest

The RestRequest object is an extension of the HttpServletRequest class with various built-in convenience methods for use in building REST interfaces.
It can be accessed by passing it as a parameter on your REST Java method:

@RestMethod(...) public Object myMethod(RestRequest req) {...}

There are many useful methods on this object, but the main ones are shown below:

7.6.3 - RestResponse

The RestResponse object is an extension of the HttpServletResponse class with various built-in convenience methods for use in building REST interfaces.
It can be accessed by passing it as a parameter on your REST Java method:

@RestMethod(...) public Object myMethod(RestResponse req) {...}

Some important methods on this class are:

7.6.4 - RequestBody

The RequestBody object is the API for accessing the body of an HTTP request.
It can be accessed by passing it as a parameter on your REST Java method:

@RestMethod(...) public Object myMethod(RequestBody body) {...}

Example:

@RestMethod(...) public void doPost(RequestBody body) { // Convert body to a linked list of Person objects. List<Person> l = body.asType(LinkedList.class, Person.class); ... }

Some important methods on this class are:

See Also:

7.6.5 - RequestHeaders

The RequestHeaders object is the API for accessing the headers of an HTTP request.
It can be accessed by passing it as a parameter on your REST Java method:

@RestMethod(...) public Object myMethod(RequestHeaders headers) {...}

Example:

@RestMethod(...) public Object myMethod(RequestHeaders headers) { // Add a default value. headers.addDefault("ETag", DEFAULT_UUID); // Get a header value as a POJO. UUID etag = headers.get("ETag", UUID.class); // Get a standard header. CacheControl = headers.getCacheControl(); }

Some important methods on this class are:

See Also:

7.6.6 - RequestQuery

The RequestQuery object is the API for accessing the GET query parameters of an HTTP request.
It can be accessed by passing it as a parameter on your REST Java method:

@RestMethod(...) public Object myMethod(RequestQuery query) {...}

Example:

@RestMethod(...) public Object myMethod(RequestQuery query) { // Get query parameters converted to various types. int p1 = query.get("p1", 0, int.class); String p2 = query.get("p2", String.class); UUID p3 = query.get("p3", UUID.class); }

An important distinction between the behavior of this object and HttpServletRequest.getParameter(String) is that the former will NOT load the body of the request on FORM POSTS and will only look at parameters found in the query string.
This can be useful in cases where you're mixing GET parameters and FORM POSTS and you don't want to inadvertently read the body of the request to get a query parameter.

Some important methods on this class are:

See Also:

7.6.7 - RequestFormData

The RequestFormData object is the API for accessing the HTTP request body as form data.
It can be accessed by passing it as a parameter on your REST Java method:

@RestMethod(...) public Object myMethod(RequestFormData query) {...}

Example:

@RestMethod(...) public Object myMethod(RequestFormData formData) { // Get query parameters converted to various types. int p1 = formData.get("p1", 0, int.class); String p2 = formData.get("p2", String.class); UUID p3 = formData.get("p3", UUID.class); }

Note that this object does NOT take GET parameters into account and only returns values found in the body of the request.

Some important methods on this class are:

See Also:

7.6.8 - @RestMethod(path)

The @RestMethod(path) annotation allows you to define URL path patterns to match against.
These patterns can contain variables of the form "{xxx}" that can be passed in directly to the Java methods as extra parameters.

In the following example, 3 separate GET request handlers are defined with different path patterns.
Note how the variables are passed in as additional arguments on the method, and how those arguments are automatically converted to the specified class type...

// Default method @RestMethod(name=GET, path="/*") public void doGetDefault() { ... } // Method with path pattern @RestMethod(name=GET, path="/xxx") public void doGetNoArgs(...) { ... } // Method with path pattern with arguments @RestMethod(name=GET, path="/xxx/{foo}/{bar}/{baz}/{bing}") public void doGetWithArgs(@Path("foo") String foo, @Path("bar") int bar, @Path("baz") MyEnum baz, @Path("bing") UUID bing) { ... }

By default, path patterns are matched using a best-match heuristic.
When overlaps occur, URLs are matched from most-specific to most-general order:

// Try first @RestMethod(name=GET, path="/foo/bar") public void method1() { ... } // Try second @RestMethod(name=GET, path="/foo/{bar}") public void method2(...) { ... } // Try third @RestMethod(name=GET, path="/foo/*") public void method3(...) { ... } // Try last @RestMethod(name=GET, path="/*") public void method4(...) { ... }

The match heuristic behavior can be overridden by the @RestMethod(priority) annotation property.
However, in practice this is almost never needed.

Paths that end with "/*" will do a prefix match on the incoming URL.
Any remainder after the match can be accessed through RequestPath.getRemainder() or parameters with the @Path("/*") annotation.
On the other hand, paths that don't end with "/*" (e.g. "/" or "/foo") will require an exact URL match, and if any remainder exists, a 404 (not found) error will be thrown.

The following example shows the distinction.

@RestMethod(name=GET, path="/*") public void doGet(@Path("/*") String remainder) { // URL path pattern can have remainder accessible through req.getRemainder(). } @RestMethod(name=PUT, path="/") public void doPut() { // URL path pattern must match exactly and will cause a 404 error if a remainder exists. }

Annotations are provided for easy access to URL parameters with automatic conversion to any parsable type.
For example, the following example can process the URL "/urlWithParams?foo=foo&bar=[1,2,3]&baz=067e6162-3b6f-4ae2-a171-2470b63dff00"...

// Example GET request with access to query parameters @RestMethod(name=GET, path="/urlWithParams") public String doGetWithParams(@Query("foo") String foo, @Query("bar") int bar, @Query("baz") UUID baz) throws Exception { return "GET /urlWithParams?foo="+foo+"&bar="+bar+"&baz="+baz; }

See Also:

7.6.9 - RequestPathMatch

The RequestPath object is the API for accessing the matched variables and remainder on the URL path.

@RestMethod(...) public Object myMethod(RequestPathMatch path) {...}

Example:

@RestMethod(..., path="/{foo}/{bar}/{baz}/*") public void doGet(RequestPathMatch path) { // Example URL: /123/qux/true/quux int foo = pm.getInt("foo"); // =123 String bar = pm.getString("bar"); // =qux boolean baz = pm.getBoolean("baz"); // =true String remainder = pm.getRemainder(); // =quux }

Some important methods on this class are:

See Also:

7.6.10 - Method Return Types

The return type can be any serializable POJO as defined in POJO Categories.
It can also be void if the method is not sending any output (e.g. a request redirect) or is setting the output using the RestResponse.setOutput(Object) method.

Example:

@RestMethod(name=GET) public String doGet() { return "Hello World!"; }

Out-of-the-box, besides POJOs, the following return types are handled as special cases:

  • InputStream
    The contents are simply piped to the output stream returned by RestResponse.getNegotiatedOutputStream().
    Note that you should call ServletResponseWrapper.setContentType(String) to set the Content-Type header if you use this object type.
  • Reader
    The contents are simply piped to the output stream returned by RestResponse.getNegotiatedWriter().
    Note that you should call ServletResponseWrapper.setContentType(String) to set the Content-Type header if you use this object type.
  • Streamable
    Interface that identifies that an object can be serialized directly to an output stream.
  • Writable
    Interface that identifies that an object can be serialized directly to a writer.
  • ZipFileList
    Special interface for sending zip files as responses.

This is controlled through the following extensible API:

REST Java methods can generate output in any of the following ways:

Example:

// Equivalent method 1 @RestMethod(name=GET, path="/example1/{personId}") public Person doGet1(@Path("personId") UUID personId) { Person p = getPersonById(personId); return p; } // Equivalent method 2 @RestMethod(name=GET, path="/example2/{personId}") public void doGet2(RestResponse res, @Path("personId") UUID personId) { Person p = getPersonById(personId); res.setOutput(p); } // (Sorta) Equivalent method 3 // (Ignores any converters or method-level properties) @RestMethod(name=GET, path="/example3/{personId}") public void doGet3(RestRequest req, RestResponse res, @Path("personId") UUID personId) { Person p = getPersonById(personId); String accept = req.getHeader("Accept", "text/json"); WriterSerializer s = res.getSerializerGroup().getWriterSerializer(accept); res.setContentType(s.getResponseContentType()); s.serialize(p, res.getNegotiatedWriter()); }

See Also:

7.6.11 - ReaderResource

The ReaderResource class is a convenience object for defining thread-safe reusable character-based responses.
In essence, it's a container for character data with optional response headers and support for resolving SVL variables.

The class is annotated with @Response which allows it to be returned as responses by REST methods.

Example:

@RestMethod public Object sayHello(RestRequest req) { // Return a reader resource loaded from a file with support for request-time SVL variables. return ReaderResource.create() .contents(new File("helloWorld.txt")) .varResolver(req.getVarResolver()) .header("Cache-Control", "no-cache") .mediaType(TEXT_PLAIN) .build(); }

7.6.12 - StreamResource

The StreamResource class is the binary equivalent to the ReaderResource object.
In essence, it's a container for binary data with optional response headers.

The class is annotated with @Response which allows it to be returned as responses by REST methods.

Example:

@RestMethod(...) public Object showPicture(RestRequest req) { // Return a stream resource loaded from a file. return StreamResource.create() .contents(new File("mypicture.png")) .header("Cache-Control", "no-cache") .mediaType(IMAGE_PNG) .build(); }

7.6.13 - @RestMethod(matchers)

RestMatchers are used to allow multiple Java methods to be tied to the same HTTP method and path, but differentiated by some request attribute such as a specific header value.

Example:

// GET method that gets invoked for administrators @RestMethod(name=GET, path="/*", matchers=IsAdminMatcher.class) public Object doGetForAdmin() { ... } // GET method that gets invoked for everyone else @RestMethod(name=GET, path="/*") public Object doGetForEveryoneElse() { ... }

The interface for matchers is simple:

public class IsAdminMatcher extends RestMatcher { @Override /* RestMatcher */ public boolean matches(RestRequest req) { return req.isUserInRole("ADMINS_GROUP"); } }

Notes:
  • If no methods are found with a matching matcher, a 412 Precondition Failed status is returned.
  • If multiple matchers are specified on the same method, ONLY ONE matcher needs to match for the method to be invoked.
  • Note that you CANNOT define identical paths on different methods UNLESS you use matchers.
    That includes paths that are only different in variable names (e.g. "/foo/{bar}" and "/foo/{baz}").
    If you try to do so, a ServletException will be thrown on startup.
  • Methods with matchers take precedence over methods without.
    Otherwise, methods are attempted in the order they appear in the class.
See Also:

7.6.14 - Predefined Responses

Predefined response beans are provided for all standard HTTP responses.
These can be used as-is or extended to provide customized HTTP responses.

Examples:

@RestMethod(name="POST", path="/pets") public Ok addPet(@Body Pet pet) { addPet(Pet); // Predefined "200 OK" response bean. return new Ok(); // Could also use Ok.OK instance }

@RestMethod(name="POST", path="/pets") public SeeOther addPet(@Body Pet pet) { addPet(Pet); // Predefined "302 See Other" response bean with redirect to /pets. return new SeeOther("servlet:/pets"); }

These predefined response beans are an example of @Response-annotated objects that are describe in detail later.
Without going into details, this is how the SeeOther is defined:

@Response( code=303 // Set automatically on response, description="See Other" // Used in generated Swagger ) public class SeeOther { private final String message; private final URI location; // Constructors omitted. // Used to populate Location response header. @ResponseHeader(name="Location") public URI getLocation() { return location; } // Used during serialization. @ResponseBody public String toString() { return message; } }

The SeeOtherRoot class shows how these predefined beans can be extended.

@Response( description="Redirect to servlet root" // Override description in generated Swagger. ) public class SeeOtherServletRoot extends SeeOther { public SeeOtherServletRoot() { super(URI.create("servlet:/")); } }

Note that the runtime behavior of the following code is identical to the example above.
However, the important distinction is that in the previous example, the 302 response would show in the generated Swagger (since we can see the response through reflection), whereas it will NOT show up in the following example (since all we see is an Object response).

@RestMethod(name="POST", path="/pets") public Object addPet(@Body Pet pet) { addPet(Pet); // Note the Object return type. return new SeeOther("servlet:/pets"); }

7.6.15 - Predefined Exceptions

Exceptions are defined for all standardized HTTP responses. These can be used to trigger HTTP errors simply by throwing an exception.

These are identical in behavior to the Predefined Responses in the previous section, except these are meant to be thrown instead of returned.

Example:

@RestMethod(name="GET", path="/user/login") public Ok login( @FormData("username") String username, @FormData("password") String password, ) throws Unauthorized { if (! isOK(username, password)) throw new Unauthorized("You're not welcome!"); return Ok.OK; }

These exception extend from RuntimeException, so they can optionally be specified in the thrown declaration of the method.
The important distinction is that when part of the thrown declaration, they show up in the generated Swagger documentation, whereas they don't if not. This behavior can be used to define what error conditions show in your Swagger doc.

7.6.16 - Predefined Helper Beans

The org.apache.juneau.rest.helper package contains several predefined beans to help when constructing REST interfaces.

ResourceDescription, ResourceDescrptions

The ResourceDescription class is a bean with name/description properties for labeling and linking to child resources.
The following examples is pulled from the REST examples:

@Resource public class PredefinedLabelsResource { @RestMethod(name=GET, path="/") public ResourceDescription[] getChildMethods() { return new ResourceDescription[] { new ResourceDescription("beanDescription", "BeanDescription"), new ResourceDescription("htmlLinks", "HtmlLink") }; } }

It get rendered as a table of name/description columns with links to child methods:

The internals of the class show it simply has two bean properties with a link annotation defined on the name property:

public class ResourceDescription { // Renders as hyperlink when serialized as HTML. @Html(link="servlet:/{name}") public String getName() {...} public String getDescription() {...} }

ResourceDescriptions is a convenience class for doing the same.
The example above can also be written as follows (which you'll notice is more concise):

@Resource public class PredefinedLabelsResource { @RestMethod(name=GET, path="/") public ResourceDescriptions getChildMethods() { return new ResourceDescriptions() .append("beanDescription", "BeanDescription") .append("htmlLinks", "HtmlLink"); } }

@HtmlLink, LinkString

The @HtmlLink annotation can also be useful for rendering custom hyperlinks:

@RestMethod public MyLink[] htmlLinks() { return new MyLink[] { new MyLink("apache", "http://apache.org"), new MyLink("juneau", "http://juneau.apache.org") }; }

@HtmlLink(nameProperty="name", hrefProperty="href") public class MyLink { // Simple bean properties. public String name, href; public MyLink(String name, String href) { this.name = name; this.href = href; } }

The LinkString bean is a predefined @HtmlLink bean provided to simplify specifying actions.
The following is equivalent to above.

@RestMethod public LinkString[] htmlLinks() { return new LinkString[] { new LinkString("apache", "http://apache.org"), new LinkString("juneau", "http://juneau.apache.org") }; }

Both examples render the following consisting of a list of hyperlinks:

In all other languages, it gets serialized as a simple bean with two properties.

BeanDescription

The BeanDescription class provides a simple view of a bean and it's properties.

@RestMethod(name=GET, path="/beanDescription") public BeanDescription getBeanDescription() { return new BeanDescription(Person.class); }

This example renders the following:

ChildResourceDescriptions

The ChildResourceDescriptions is a convenience bean for generating a table of child resources.

The BasicRestServletGroup class uses this to generate router pages:

@RestResource public abstract class BasicRestServletGroup extends BasicRestServlet { @RestMethod(name=GET, path="/", summary="Navigation page") public ChildResourceDescriptions getChildren(RestRequest req) throws Exception { return new ChildResourceDescriptions(req); } }

Note that all it requires is a RestRequest object and it will generate a router page using reflection against the resource class.

For example, the RootResources page in the REST examples renders the child resources attached to the root resource:

The RootResources page consists of the following and extends from the BasicRestServletGroup class:

@RestResource( ... children={ HelloWorldResource.class, PetStoreResource.class, DtoExamples.class, PhotosResource.class, SqlQueryResource.class, ConfigResource.class, LogsResource.class, DebugResource.class, ShutdownResource.class } ) public class RootResources extends BasicRestServletJenaGroup {}

SeeOtherRoot

The SeeOtherRoot class can be used to redirect to the root URI of a resource class.

@RestMethod(name="POST", path="/pets") public SeeOtherRoot addPet(@Body Pet pet) { addPet(Pet); // Redirects to the servlet root URL. return SeeOtherRoot.INSTANCE; }

The runtime behavior is the same as the following:

@RestMethod(name="POST", path="/pets") public SeeOther addPet(@Body Pet pet) { addPet(Pet); // Redirects to the servlet root URL. return new SeeOther(URI.create("servlet:/")); }

One distinction is that the former defines the description "Redirect to servlet root" in the generated Swagger documentation.

7.7 - restRPC

The restRPC (RPC over REST) API allows the creation of client-side remote proxy interfaces for calling methods on server-side POJOs using entirely REST.

Remote Interfaces

The following example shows a remote interface:

@RemoteInterface // Annotation is optional public interface IAddressBook { void init() throws Exception; List<Person> getPeople(); List<Address> getAddresses(); int createPerson(CreatePerson cp) throws Exception; Person findPerson(int id); Address findAddress(int id); Person findPersonWithAddress(int id); Person removePerson(int id); }

The requirements for a remote interface method are:

Throwables with public no-arg or single-arg-string constructors are automatically recreated on the client side when thrown on the server side.

Client side

Remote Interface proxies are instantiated on the client side using one of the following methods:

Since we build upon the existing RestClient API, we inherit all of it's features.
For example, convenience methods for setting POJO filters and properties to customize the behavior of the serializers and parsers, and the ability to provide your own customized Apache HttpClient for handling various scenarios involving authentication and Internet proxies.

Here's an example of the above interface being used:

// Create a RestClient using JSON for serialization, and point to the server-side remote interface servlet. RestClient client = RestClient.create() .json() .rootUrl("http://localhost:10000/remote") .build(); // Create a proxy interface. IAddressBook ab = client.getRrpcInterface(IAddressBook.class); // Invoke a method on the server side and get the returned result. Person p = ab.createPerson( new Person( "John Smith", "Aug 1, 1999", new Address("My street", "My city", "My state", 12345, true) ) );

Under the covers, this method call gets converted to a REST POST.

HTTP POST http://localhost:10000/remote/org.apache.juneau.examples.addressbook.IAddressBook/createPerson(org.apache.juneau.examples.addressbook.Person) Accept: application/json Content-Type: application/json [ { "name":"John Smith", "birthDate":"Aug 1, 1999", "addresses":[ { "street":"My street", "city":"My city", "state":"My state", "zip":12345, "isCurrent":true } ] } ]

Note that the body of the request is an array.
This array contains the serialized arguments of the method.
The object returned by the method is then serialized as the body of the response.

Server side

There are two ways to expose remote interfaces on the server side:

  1. Extending from RrpcServlet.
  2. Using a @RestMethod(name=RRPC) annotation on a Java method.

In either case, the proxy communications layer is pure REST.
Therefore, in cases where the interface classes are not available on the client side, the same method calls can be made through pure REST calls.
This can also aid significantly in debugging, since calls to the remote interface service can be made directly from a browser with no coding involved.

RrpcServlet

The RrpcServlet class is a simple specialized servlet with an abstract getServiceMap() method to define the server-side POJOs:

@RestResource( path="/remote" ) public class SampleRrpcServlet extends RrpcServlet { // Our server-side POJO. private AddressBook addressBook = new AddressBook(); @Override /* RrpcServlet */ protected Map<Class<?>,Object> getServiceMap() throws Exception { Map<Class<?>,Object> m = new LinkedHashMap<Class<?>,Object>(); // 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!). m.put(IAddressBook.class, addressBook); m.put(AddressBook.class, addressBook); return m; } }

@RestMethod(name=RRPC)

The @RestMethod(name=RRPC) 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:

// Our exposed interface. @RestMethod(name=RRPC, path="/addressbookproxy/*") public IAddressBook getProxy() { return addressBook; }

RrpcServlet in a browser

If you point your browser to the servlet above, you get a list of available interfaces:

http://localhost:10000/remote

Clicking the hyperlinks on each shows you the list of methods that can be invoked on that service.
Note that the IAddressBook link shows that you can only invoke methods defined on that interface, whereas the AddressBook link shows ALL public methods defined on that class.

IAddressBook

http://localhost:10000/remote/org.apache.juneau.examples.addressbook.IAddressBook

Since AddressBook extends from LinkedList, you may notice familiar collections framework methods listed.

AddressBook

http://localhost:10000/remote/org.apache.juneau.examples.addressbook.AddressBook

Let's see how we can interact with this interface through nothing more than REST calls to get a better idea on how this works.
We'll use the same method call as in the introduction.
First, we need to create the serialized form of the arguments:

Object[] args = new Object[] { new CreatePerson("Test Person", AddressBook.toCalendar("Aug 1, 1999"), new CreateAddress("Test street", "Test city", "Test state", 12345, true)) }; String asJson = SimpleJsonSerializer.DEFAULT_READABLE.toString(args); System.err.println(asJson);

That produces the following JSON output:

[ { name: 'Test Person', birthDate: 'Aug 1, 1999', addresses: [ { street: 'Test street', city: 'Test city', state: 'Test state', zip: 12345, isCurrent: true } ] } ]

Note that in this example we're using JSON.
However, various other content types can also be used such as XML, URL-Encoding, UON, or HTML.
In practice however, JSON will preferred since it is often the most efficient.

Next, we can use a tool such as Poster to make the REST call.
Methods are invoked by POSTing the serialized object array to the URI of the interface method. In this case, we want to POST our JSON to the following URL:

http://localhost:10000/remote/org.apache.juneau.examples.addressbook.IAddressBook/createPerson(org.apache.juneau.examples.addressbook.CreatePerson)


Make sure that we specify the Content-Type of the body as text/json.
We also want the results to be returned as JSON, so we set the Accept header to text/json as well.

When we execute the POST, we should see the following successful response whose body contains the returned Person bean serialized to JSON:

From there, we could use the following code snippet to reconstruct the response object from JSON:

String response = "output from above"; Person p = JsonParser.DEFAULT.parse(response, Person.class);

If we alter our servlet to allow overloaded GET requests, we can invoke methods using nothing more than a browser...

@RestResource( path="/remote", // Allow us to use method=POST from a browser. allowedMethodParams="*" ) public class SampleRrpcServlet extends RrpcServlet {

For example, to invoke the getPeople() method on our bean:

http://localhost:10000/remote/org.apache.juneau.examples.addressbook.IAddressBook/getPeople?method=POST

Here we call the findPerson(int) method to retrieve a person and get the returned POJO (in this case as HTML since that's what's in the Accept header when calling from a browser):

http://localhost:10000/remote/org.apache.juneau.examples.addressbook.IAddressBook/findPerson(int)?method=POST&body=@(3)

When specifying the POST body as a &body parameter, the method arguments should be in UON notation.
See UonSerializer for more information about this encoding.
Usually you can also pass in JSON if you specify &Content-Type=text/json in the URL parameters but passing in unencoded JSON in a URL may not work in all browsers.
Therefore, UON is preferred.

The hyperlinks on the method names above lead you to a simple form-entry page where you can test passing parameters in UON notation as URL-encoded form posts.

Sample form entry page
Sample form entry page results

7.8 - OpenAPI Schema Part Parsing

Parameters annotated with any of the following are parsed using the registered OpenApiParser and therefore support OpenAPI syntax and validation:

For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9") in a query parameter can be converted to a 2-dimensional array of Longs:

@RestMethod(method="GET", path="/testQuery") public void testQuery( @Query( name="queryParamName", collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ), minLength=1, maxLength=10 ) Long[][] queryParameter ) {...}

Input will be converted based on the types and formats defined in the schema definition.
Input validations such as minLength/maxLength that don't match the input will result in automatic 400 Bad Request responses.

The following shows the same for a request body:

@RestMethod(method="POST", path="/testBody") public void testBody( @Body( parsers=OpenApiParser.class, defaultContentType="text/openapi", schema=@Schema( items=@Items( collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ) ), minLength=1, maxLength=10 ) ) Long[][] body ) {...}

The list of valid POJO types for parameters depends on type and format of the value or items/entries of the value.
For example, instead of Longs in the example above, we could also define a 2-dimensional array of POJOs convertible from Longs:

@RestMethod(method="POST", path="/2dLongArray") public void testBody(@Body(...) MyPojo[][] body) {...} // POJO convertible from a Long. public class MyPojo { public MyPojo(Long input) {...} }

Or even POJOs that take in arrays of Longs[]:

@RestMethod(method="POST", path="/2dLongArray") public void testBody(@Body(...) MyPojo[] body) {...} // POJO convertible from a Long[]. public class MyPojo { public MyPojo(Long[] input) {...} }

Or even POJOs that take in the whole 2-dimensional array:

@RestMethod(method="POST", path="/2dLongArray") public void testBody(@Body(...) MyPojo body) {...} // POJO convertible from a Long[][]. public class MyPojo { public MyPojo(Long[][] input) {...} }

As you can see, the complexity of possible input types expands significantly.
For more information about valid parameter types, see OpenAPI Parsers

7.9 - OpenAPI Schema Part Serializing

Parameters annotated with any of the following are serialized using the registered OpenApiSerializer and therefore support OpenAPI syntax and validation:

For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9") in a response header can be converted to a 2-dimensional array of Longs:

@RestMethod(method="GET", path="/testResponseHeader") public void testResponseHeader( @ResponseHeader( name="My-Header", collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ), minLength=1, maxLength=10 ) Value<Long[][]> header ) { header.set(new Long[][]{...}); }

The following shows the same for a response body:

@RestMethod(method="GET", path="/testResponseBody") public void testResponseBody( @Response( serializers=OpenApiSerialier.class, defaultAccept="text/openapi", schema=@Schema( items=@Items( collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ) ), minLength=1, maxLength=10 ) ) Value<Long[][]> responseBody ) {...}

For more information about the valid parameter types, see OpenAPI Serializers

7.10 - HTTP-Part Annotations

The annotations used for defining the schema for request HTTP parts are:

The annotations used for defining the schema for response HTTP parts are:

The sub-annotations used in the annotation above are:

Other Notes:
  • Annotation parameter values will be aggregated when used on POJO parent and child classes.
    Values on child classes override values on parent classes.
  • Annotation parameter values will be aggregated when used on both POJOs and REST methods.
    Values on methods override values on POJO classes.

7.10.1 - @Body

The @Body annotation is used to identify POJOs to be used as the body of an HTTP request.

Examples:

// Defined on parameter @RestMethod(name=POST) public void addPet(@Body Pet pet) {...}

// Defined on POJO class @RestMethod(name=POST) public void addPet(Pet pet) {...} @Body public class Pet {...}

This is functionally equivalent to the following code:

@RestMethod(name=POST) public void addPet(RestRequest req) { Person person = req.getBody().asType(Pet.class); ... }

Any of the following types can be used for the parameter or POJO class (matched in the specified order):

  1. Reader
    @Body annotation is optional.
    Content-Type is ignored.
  2. InputStream
    @Body annotation is optional.
    Content-Type is ignored.
  3. Any Parsable POJO type.
    Content-Type is required to identify correct parser.
  4. Objects convertible from Reader by having one of the following non-deprecated methods:
    • public T(Reader in) {...}
    • public static T create(Reader in) {...}
    • public static T fromReader(Reader in) {...}
    Content-Type must not be present or match an existing parser so that it's not parsed as a POJO.
  5. Objects convertible from InputStream by having one of the following non-deprecated methods:
    • public T(InputStream in) {...}
    • public static T create(InputStream in) {...}
    • public static T fromInputStream(InputStream in) {...}
    Content-Type must not be present or match an existing parser so that it's not parsed as a POJO.
  6. Objects convertible from String by having one of the following non-deprecated methods:
    • public T(String in) {...}
    • public static T create(String in) {...}
    • public static T fromString(String in) {...}
    • public static T parse(String in) {...}
    • public static T parseString(String in) {...}
    • public static T forName(String in) {...}
    • public static T forString(String in) {...}
    Note that this also includes all enums.

The OpenApiSerializer class can be used to serialize HTTP bodies to OpenAPI-based output.

For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9") can be converted to a 2-dimensional array of Longs:

// Body is a pipe-delimited list of comma-delimited lists of longs. @RestMethod( method="POST", path="/testBody", serializers=OpenApiSerializers.class, defaultAccept="text/openapi" ) public void testBody( @Body( schema=@Schema( items=@Items( collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ) ), minLength=1, maxLength=10 ) ) Long[][] body ) {...}

Input will be converted based on the types and formats defined in the schema definition.
Input validations such as minLength/maxLength that don't match the input will result in automatic 400 Bad Request responses.

For more information about valid parameter types when using OpenAPI parsing, see OpenAPI Parsers

The @Body annotation is also used for supplying swagger information about the body of the request.
This information is used to populate the auto-generated Swagger documentation and UI.

Examples:

// Normal @Body( description="Pet object to add to the store", required=true, example="{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}" )

// Free-form // Note the extra field @Body({ "description: 'Pet object to add to the store',", "required: true,", "example: {name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}," "x-extra: 'extra field'" })

Default REST SVL Variables (e.g. "$L{my.localized.variable}") are supported on annotation fields.

Example:

// Localized @Body( description="$L{PetObjectDescription}" )

Other Notes:
  • Annotation parameter values will be aggregated when used on POJO parent and child classes.
    Values on child classes override values on parent classes.
  • Annotation parameter values will be aggregated when used on both POJOs and REST methods.
    Values on methods override values on POJO classes.
See Also:

7.10.2 - @FormData

The @FormData annotation is used to retrieve request form post entries.

  • FormData
    • _default - Default value if not present.
    • _enum - Input validation. Must match one of the values.
    • allowEmptyValue - Input validation. Allow empty value.
    • api() - Free-form Swagger JSON.
    • collectionFormat - How collections of items are formatted.
    • description - Description.
    • example() - Serialized example.
    • exclusiveMaximum - Input validation. Whether maximum is exclusive.
    • exclusiveMinimum - Input validation. Whether minimum is exclusive.
    • format - The schema type format.
    • items - The schema of items in a collection.
    • maximum - Input validation. Maximum numeric value.
    • maxItems - Input validation. Maximum number of items in a collection.
    • maxLength - Input validation. Maximum length of a string.
    • minimum - Input validation. Minimum numeric value.
    • minItems - Input validation. Minimum number of items in a collection.
    • minLength - Input validation. Minimum length of a string.
    • multipleOf - Input validation. Number must be a multiple of.
    • name - Form data entry name.
    • parser - Override the part parser.
    • pattern - Input validation. Must match regular expression.
    • required - Input validation. Form data entry must be present.
    • type - The schema type.
    • uniqueItems - Input validation. Collections must contain unique items only.
    • value - Free-form Swagger JSON.

The most typical scenario is to simply use the value field to define form data parameter names:

Example:

@RestMethod(name=POST) public void doPost( @FormData("p1") int p1, @FormData("p2") String p2, @FormData("p3") UUID p3) {...}

This is functionally equivalent to the following code:

@RestMethod(name=POST) public void doPost(RestRequest req) { RequestFormData fd = req.getFormData(); int p1 = fd.get("p1", 0, int.class); String p2 = fd.get("p2", String.class); UUID p3 = fd.get("p3", UUID.class); }

The special name "*" (or blank) can be used to represent all values. When used, the data type must be a Map or bean.

Examples:

// Multiple values passed as a map. @RestMethod(name=POST) public void doPost(@FormData("*") Map<String,Object> map) {...}

// Same, but name "*" is inferred. @RestMethod(name=POST) public void doPost(@FormData Map<String,Object> map) {...}

// Multiple values passed as a bean. @RestMethod(name=POST) public void doPost(@FormData MyBean bean) {...}

The registered REST_partParser is used to convert strings to POJOs and controls what POJO types are supported.
By default, this is the OpenApiParser which supports the standard Swagger-based rules for parsing.

For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9") can be converted to a 2-dimensional array of Longs:

@RestMethod(method="POST", path="/testFormData") public void testFormData( @FormData( name="formDataParamName", collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ), minLength=1, maxLength=10 ) Long[][] formDataParameter ) {...}

Input will be converted based on the types and formats defined in the schema definition.
Input validations such as minLength/maxLength that don't match the input will result in automatic 400 Bad Request responses.

For more information about valid parameter types, see OpenAPI Parsers

The @FormData annotation is also used for supplying swagger information about the HTTP part.
This information is used to populate the auto-generated Swagger documentation and UI.

Examples:

// Normal @FormData( name="name", description="Pet name", required=true, example="Doggie" )

// Free-form // Note the extra field @FormData( name="name", api={ "description: 'Pet name',", "required: true,", "example: 'Doggie'," "x-extra: 'extra field'" } )

Default REST SVL Variables (e.g. "$L{my.localized.variable}") are supported on annotation fields.

Example:

@FormData( description="$L{PetNameDescription}" )

Notes:
  • This annotation should not be combined with the @Body annotation or RestRequest.getBody() method for application/x-www-form-urlencoded POST posts, since it will trigger the underlying servlet API to parse the body content as key-value pairs resulting in empty content.
    The @Query annotation can be used to retrieve a URL parameter in the URL string without triggering the servlet to drain the body content.
See Also:

7.10.3 - @HasFormData

This annotation can be used to detect the existence of a parameter when it's not set to a particular value.

Example:

@RestMethod(name=POST) public void doPost(@HasFormData("p1") boolean p1) {...}

This is functionally equivalent to the following code:

@RestMethod(name=POST) public void doPost(RestRequest req) { boolean p1 = req.hasFormData("p1"); ... }

The parameter type must be either boolean or Boolean.

The following table shows the behavioral differences between @HasFormData and @FormData:

Body content @HasFormData("a") @FormData("a")
a=foo true "foo"
a= true ""
a true null
b=foo false null
Important note concerning FORM posts

This annotation should not be combined with the @Body annotation or RestRequest.getBody() method for application/x-www-form-urlencoded POST posts, since it will trigger the underlying servlet API to parse the body content as key-value pairs, resulting in empty content.

The @HasQuery annotation can be used to check for the existing of a URL parameter in the URL string without triggering the servlet to drain the body content.

7.10.4 - @Query

The @Query annotation is used to retrieve request URL query parameters.
It's identical to @FormData, but only retrieves the parameter from the URL string, not URL-encoded form posts.

  • Query
    • _default - Default value if not present.
    • _enum - Input validation. Must match one of the values.
    • allowEmptyValue - Input validation. Allow empty value.
    • api - Free-form Swagger JSON.
    • collectionFormat - How collections of items are formatted.
    • description - Description.
    • example - Serialized example.
    • exclusiveMaximum - Input validation. Whether maximum is exclusive.
    • exclusiveMinimum - Input validation. Whether minimum is exclusive.
    • format - The schema type format.
    • items - The schema of items in a collection.
    • maximum - Input validation. Maximum numeric value.
    • maxItems - Input validation. Maximum number of items in a collection.
    • maxLength - Input validation. Maximum length of a string.
    • minimum - Input validation. Minimum numeric value.
    • minItems - Input validation. Minimum number of items in a collection.
    • minLength - Input validation. Minimum length of a string.
    • multipleOf - Input validation. Number must be a multiple of.
    • name - Query parameter name.
    • parser - Override the part parser.
    • pattern - Input validation. Must match regular expression.
    • required - Input validation. Query parameter must be present.
    • type - The schema type.
    • uniqueItems - Input validation. Collections must contain unique items only.
    • value - Free-form Swagger JSON.

Unlike @FormData, using this annotation does not result in the servlet reading the contents of URL-encoded form posts.
Therefore, this annotation can be used in conjunction with the @Body annotation or RestRequest.getBody() method for application/x-www-form-urlencoded POST calls.

The most typical scenario is to simply use the value field to define query parameter names:

Example:

@RestMethod(name=GET) public void doGet( @Query("p1") int p1, @Query("p2") String p2, @Query("p3") UUID p3) {...}

This is functionally equivalent to the following code:

@RestMethod(name=GET) public void doGet(RestRequest req) { RequestQuery q = req.getQuery(); int p1 = q.get("p1", 0, int.class); String p2 = q.get("p2", String.class); UUID p3 = q.get("p3", UUID.class); }

The special name "*" (or blank) can be used to represent all values. When used, the data type must be a Map or bean.

Examples:

// Multiple values passed as a map. @RestMethod(name=GET) public void doGet(@Query("*") Map<String,Object> map) {...}

// Same, but name "*" is inferred. @RestMethod(name=GET) public void doGet(@Query Map<String,Object> map) {...}

// Multiple values passed as a bean. @RestMethod(name=GET) public void doGet(@Query MyBean bean) {...}

The registered REST_partParser is used to convert strings to POJOs and controls what POJO types are supported.
By default, this is the OpenApiParser which supports the standard Swagger-based rules for parsing.

For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9") can be converted to a 2-dimensional array of Longs:

@RestMethod(method="GET", path="/testQuery") public void testQuery( @Query( name="queryParamName", collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ), minLength=1, maxLength=10 ) Long[][] queryParameter ) {...}

Input will be converted based on the types and formats defined in the schema definition.
Input validations such as minLength/maxLength that don't match the input will result in automatic 400 Bad Request responses.

For more information about valid parameter types, see OpenAPI Parsers

The @Query annotation is also used for supplying swagger information about the HTTP part.
This information is used to populate the auto-generated Swagger documentation and UI.

Examples:

// Normal @Query( name="name", description="Pet name", required=true, example="Doggie" )

// Free-form // Note the extra field @Query( name="name", api={ "description: 'Pet name',", "required: true,", "example: 'Doggie'," "x-extra: 'extra field'" } )

Default REST SVL Variables (e.g. "$L{my.localized.variable}") are supported on annotation fields.

Example:

@Query( description="$L{PetNameDescription}" )

See Also:

7.10.5 - @HasQuery

Identical to @HasFormData, but only checks the existing of the parameter in the URL string, not URL-encoded form posts.

Unlike @HasFormData, using this annotation does not result in the servlet reading the contents of URL-encoded form posts. Therefore, this annotation can be used in conjunction with the @Body annotation or RestRequest.getBody() method for application/x-www-form-urlencoded POST calls.

Example:

@RestMethod(name=GET) public void doGet(@HasQuery("p1") boolean p1) {...}

This is functionally equivalent to the following code:

@RestMethod(name=GET) public void doGet(RestRequest req) { boolean p1 = req.hasQuery("p1"); ... }

The parameter type must be either boolean or Boolean.

The following table shows the behavioral differences between @HasQuery and @Query:

Query content @HasQuery("a") @Query("a")
?a=foo true "foo"
?a= true ""
?a true null
?b=foo false null

7.10.6 - @Header

The @Header annotation is used to retrieve request headers.

  • Header
    • _default - Default value if not present.
    • _enum - Input validation. Must match one of the values.
    • allowEmptyValue - Input validation. Allow empty value.
    • api - Free-form Swagger JSON.
    • collectionFormat - How collections of items are formatted.
    • description - Description.
    • example - Serialized example.
    • exclusiveMaximum - Input validation. Whether maximum is exclusive.
    • exclusiveMinimum - Input validation. Whether minimum is exclusive.
    • format - The schema type format.
    • items - The schema of items in a collection.
    • maximum - Input validation. Maximum numeric value.
    • maxItems - Input validation. Maximum number of items in a collection.
    • maxLength - Input validation. Maximum length of a string.
    • minimum - Input validation. Minimum numeric value.
    • minItems - Input validation. Minimum number of items in a collection.
    • minLength - Input validation. Minimum length of a string.
    • multipleOf - Input validation. Number must be a multiple of.
    • name - Header name.
    • parser - Override the part parser.
    • pattern - Input validation. Must match regular expression.
    • required - Input validation. Header must be present.
    • type - The schema type.
    • uniqueItems - Input validation. Collections must contain unique items only.
    • value - Free-form Swagger JSON.

The most typical scenario is to simply use the value field to define header parameter names:

Example:

@RestMethod(name=GET) public void doGet(@Header("ETag") UUID etag) {...}

This is functionally equivalent to the following code:

@RestMethod(name=GET) public void doGet(RestRequest req) { RequestHeaders h = req.getHeaders(); UUID etag = h.get("ETag", UUID.class); }

The special name "*" (or blank) can be used to represent all values. When used, the data type must be a Map or bean.

Examples:

// Multiple values passed as a map. @RestMethod(name=GET) public void doGet(@Header("*") Map<String,Object> map) {...}

// Same, but name "*" is inferred. @RestMethod(name=GET) public void doGet(@Header Map<String,Object> map) {...}

// Multiple values passed as a bean. @RestMethod(name=GET) public void doGet(@Header MyBean bean) {...}

The registered REST_partParser is used to convert strings to POJOs and controls what POJO types are supported.
By default, this is the OpenApiParser which supports the standard Swagger-based rules for parsing.

For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9") can be converted to a 2-dimensional array of Longs:

@RestMethod(method="GET", path="/testHeader") public void testHeader( @Header( name="My-Header", collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ), minLength=1, maxLength=10 ) Long[][] myHeader ) {...}

Input will be converted based on the types and formats defined in the schema definition.
Input validations such as minLength/maxLength that don't match the input will result in automatic 400 Bad Request responses.

For more information about valid parameter types, see OpenAPI Parsers

The @Header annotation is also used for supplying swagger information about the HTTP part.
This information is used to populate the auto-generated Swagger documentation and UI.

Examples:

// Normal @Header( name="Pet-Name", description="Pet name", required=true, example="Doggie" )

// Free-form // Note the extra field @Header( name="Pet-Name", api={ "description: 'Pet name',", "required: true,", "example: 'Doggie'," "x-extra: 'extra field'" } )

Default REST SVL Variables (e.g. "$L{my.localized.variable}") are supported on annotation fields.

Example:

@Header( description="$L{PetNameDescription}" )

See Also:

7.10.7 - @Path

The @Path annotation is used to retrieve request path parameters.

  • Path
    • _enum - Input validation. Must match one of the values.
    • allowEmptyValue - Input validation. Allow empty value.
    • api - Free-form Swagger JSON.
    • collectionFormat - How collections of items are formatted.
    • description - Description.
    • example - Serialized example.
    • exclusiveMaximum - Input validation. Whether maximum is exclusive.
    • exclusiveMinimum - Input validation. Whether minimum is exclusive.
    • format - The schema type format.
    • items - The schema of items in a collection.
    • maximum - Input validation. Maximum numeric value.
    • maxLength - Input validation. Maximum length of a string.
    • minimum - Input validation. Minimum numeric value.
    • minLength - Input validation. Minimum length of a string.
    • multipleOf - Input validation. Number must be a multiple of.
    • name - Path variable name.
    • parser - Override the part parser.
    • pattern - Input validation. Must match regular expression.
    • type - The schema type.
    • value - Free-form Swagger JSON.

The most typical scenario is to simply use the value field to define path parameter names:

Example:

@RestMethod(name=GET, path="/myurl/{foo}/{bar}/{baz}/*") public void doGet( @Path("foo") String foo, @Path("bar") int bar, @Path("baz") UUID baz, @Path("/*") String remainder ) {...}

This is functionally equivalent to the following code:

@RestMethod(name=GET, path="/myurl/{foo}/{bar}/{baz}/*") public void doGet(RestRequest req) { RequestPath p = req.getPathMatch(); String foo = p.getString("foo"); int bar = p.get("bar", int.class); UUID baz = p.get("baz", UUID.class); String remainder = p.getRemainder(); }

Note that the path variable name "/*" can be used to represent the remainder of the path match.

The special name "*" (or blank) can be used to represent all values. When used, the data type must be a Map or bean.

Examples:

// Multiple values passed as a map. @RestMethod(name=GET, path="/{a}/{b}/{c}/*") public void doGet(@Path("*") Map<String,Object> map) {...}

// Same, but name "*" is inferred. @RestMethod(name=GET, path="/{a}/{b}/{c}/*") public void doGet(@Path Map<String,Object> map) {...}

// Multiple values passed as a bean. @RestMethod(name=GET, path="/{a}/{b}/{c}/*") public void doGet(@Path MyBean bean) {...}

The registered REST_partParser is used to convert strings to POJOs and controls what POJO types are supported.
By default, this is the OpenApiParser which supports the standard Swagger-based rules for parsing.

For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9") can be converted to a 2-dimensional array of Longs:

@RestMethod(method="POST", path="/testPath/{pathParam}") public void testPath( @Path( name="pathParam", collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ), minLength=1, maxLength=10 ) Long[][] pathParameter ) {...}

Input will be converted based on the types and formats defined in the schema definition.
Input validations such as minLength/maxLength that don't match the input will result in automatic 400 Bad Request responses.

For more information about valid parameter types, see OpenAPI Parsers

The @Path annotation is also used for supplying swagger information about the HTTP part.
This information is used to populate the auto-generated Swagger documentation and UI.

Examples:

// Normal @Path( name="name", description="Pet name", example="Doggie" )

// Free-form // Note the extra field @Path( name="name", api={ "description: 'Pet name',", "example: 'Doggie'," "x-extra: 'extra field'" } )

Default REST SVL Variables (e.g. "$L{my.localized.variable}") are supported on annotation fields.

Example:

@Path( description="$L{PetNameDescription}" )

See Also:

7.10.8 - @Request

The @Request annotation can be applied to a parameter interface type of a @RestMethod-annotated method to identify it as an interface for retrieving HTTP parts through a bean-like interface.

Example:

@RestMethod(path="/pets/{petId}") public void putPet(UpdatePet updatePet) {...} @Request public interface UpdatePet { @Path int getPetId(); @Query(name="verbose") boolean isDebug(); @Header("*") Map<String,Object> getAllHeaders(); @Body Pet getPet(); }

The example above is identical in behavior to specifying individual annotated parameters on the @RestMethod-annotated method:

@RestMethod(path="/pets/{petId}") public void putPet( @Path("petId") int petId, @Query("verbose") boolean debug, @Header("*") Map<String,Object> allHeaders, @Body Pet pet ) {...}

The return types of the getters must be the supported parameter types for the HTTP-part annotation used.
Schema-based serialization and parsing is used just as if used as individual parameter types.
Annotations used are the exact same used on REST parameters and have all the same feature support including automatic Swagger validation and documentation.

Example:

@Request public interface Request { // Schema-based query parameter: Pipe-delimited lists of comma-delimited lists of integers. @Query( collectionFormat="pipes" items=@Items( items=@SubItems( collectionFormat="csv" type="integer", minimum=1, maximum=100 ), maximumLength=10 ) ) int[][] getPipedCdlInts(); }

For clarity, the @Request annotation can be defined on the parameter, class, or both.

Example:

@RestMethod(path="/pets/{petId}") public void putPet(@Request UpdatePet updatePet) {...} @Request public interface UpdatePet {...}

7.10.9 - @Response

The @Response annotation is used to identify schema information about an HTTP response.

It can be used in the following locations:

  • Exception classes thrown from @RestMethod-annotated methods.
  • Return type classes of @RestMethod-annotated methods.
  • @RestMethod-annotated methods themselves.
  • Arguments and argument-types of @RestMethod-annotated methods.

When the @Response annotation is applied to classes, the following annotations can be used on public non-static methods of the class to identify parts of a response:

@Resource on exception classes

When applied to an exception class, this annotation defines Swagger schema and information on non-200 return types.

The following example shows the @Response annotation used to define an exception for an invalid login attempt:

// Our annotated exception. @Response( code=401, description="Invalid username or password provided" // Description show in Swagger ) public class InvalidLogin extends Exception { public InvalidLogin() { super("Invalid username or password."); // Message sent in response } } // Our REST method that throws an annotated exception. @RestMethod(name="GET", path="/user/login") public Ok login( @FormData("username") String username, @FormData("password") String password ) throws InvalidLogin { checkCredentials(username, password); return new Ok(); }

Custom exceptions can also extend from one of the predefined HTTP exceptions such as the Unauthorized exception:

// Our annotated exception. @Response( description="Invalid username or password provided" // Overridden from parent class ) public class InvalidLogin extends Unauthorized { public InvalidLogin() { super("Invalid username or password."); } } // Parent predefined exception class. @Response( code=401, description="Unauthorized" ) public class Unauthorized extends RestException {...}

@Resource on return type classes

When applied type classes returned by a Java method, this annotation defines schema and Swagger information on the body of responses.

In the example above, we're using the Ok class which is defined like so:

@Response( code=200, description="OK" ) public class Ok { @ResponseBody public String toString() { return "OK"; } }

Another example showing how a redirect can be defined:

@Response( code=307, description="Temporary Redirect" ) public class Redirect { private final URI location; public Redirect(URI location) { this.location = location; } @ResponseHeader( name="Location", format="uri" ) public URI getLocation() { return location; } @ResponseBody public String toString() { return "Temporary Redirect"; } }

// Usage @RestMethod(method=POST) public Redirect addPet(Pet pet) { // Redirect to servlet root return new Redirect(URI.create("servlet:/")); }

@Resource on @RestMethod-annotated methods

The @Response annotation can also be applied to the Java method itself which is effectively the same as applying it to the return type (albeit for this method only).

@RestMethod(name="GET", path="/user/login") @Response(code=200, description="OK") public Ok login( @FormData("username") String username, @FormData("password") String password ) throws InvalidLogin { checkCredentials(username, password); return new Ok(); }

The @Response annotation can be simultaneously on both the Java method and return type.
When used in both locations, the annotation values are combined, but values defined on the method return annotation take precedence over the values defined on the type.

@Resource on @RestMethod-annotated method parameters

The @Response annotation can also be applied to the Java method parameters when the parameter type is Value (a placeholder for objects).

@RestMethod(name="GET", path="/user/login") public void login( @FormData("username") String username, @FormData("password") String password, @Response(code=200, description="Login succeeded") Value<String> body ) throws InvalidLogin { checkCredentials(username, password); body.set("OK"); }

@Response-annotated types can also be used as value parameters:

@RestMethod(...) public void login( ... @Response Value<Ok> res ) throws InvalidLogin { ... res.set(new Ok()); }

In the above example, the @Response annotation is optional since it is inferred from the class that it's a @Response bean.

@RestMethod(name="GET", path="/user/login") public void login( ... Value<Ok> res // @Response annotation not needed. ) throws InvalidLogin { ... res.set(new Ok()); }

@ResponseStatus on methods of @Response-annotated types

The @ResponseStatus annotation can be used on the method of a @Response-annotated class to identify HTTP response statuses other than 200 (the default).

Example:

@Response public class AddPetSuccess { @ResponseStatus public int getStatus() { return 201; } @Override public String toString() { return "Pet was successfully added"; } }

@ResponseHeader on methods of @Response-annotated types

The @ResponseHeader annotation can be used on the method of a @Response-annotated class to identify a header to add to the response.

Example:

@Response public class AddPetSuccess { @ResponseHeader( name="X-PetId", type="integer", format="int32", description="ID of added pet.", example="123" ) public int getPetId() {...} }

@ResponseBody on methods of @Response-annotated types

The @ResponseBody annotation can be used on the method of a @Response-annotated class to identify a POJO as the body of the HTTP response.

Example:

@Response public class AddPetSuccess { @ResponseBody public Pet getPet() {...} }

If a @Response class does not have a @ResponseBody-annotated method, then the response object itself is serialized in the response (typically using toString()).

Notes about OpenAPI part serialization

By default, POJOs representing the body of the request are serialized using the Juneau serializer matching the requesting Accept header.
The OpenApiSerializer class can be used to serialize response bodies using OpenAPI rules.

The following examples show part-schema-based serialization of response bodies:

@RestResource public class ExampleResource { // Example 1 - String[] should be serialized using part serializer. @Response( serializers=OpenApiSerializer.class, defaultAccept="text/openapi" ) @RestMethod public String[] example1() { return new String[]{"foo","bar"}; } // Example 2 - Same as above. Annotation on parameter. @RestMethod public void example2( @Response( serializers=OpenApiSerializer.class, defaultAccept="text/openapi" ) Value<String[]> body ) { body.set(new String[]{"foo","bar"}); } }

The @Response(schema) annotation can be used to define the format of the output using OpenAPI-based rules.

@RestResource public class ExampleResource { @Response( serializers=OpenApiSerializer.class, defaultAccept="text/openapi", schema=@Schema(collectionFormat="pipes") ) @RestMethod public String[] example1() { return new String[]{"foo","bar"}; } }

Swagger documentation

The attributes on this annotation are also used to populate the generated Swagger for the method.
For example, in the case of the InvalidLogin example above, the following Swagger is generated:

'/user/login': { get: { responses: { 401: { description: 'Invalid username or password provided' } } } }

Automatic HTTP status

When the @Response(code) value is specified, the HTTP status is automatically set to that value on the response regardless of how it's used.

The following two examples are equivalent:

@RestMethod(name="GET", path="/ok") public void sendContinue( @Response(code=100) Value<String> body ) { body.set("OK"); }

@RestMethod(name="GET", path="/ok") public void sendContinue(RestResponse res) { res.setStatus(100); res.setOutput("OK"); }

See Also:

7.10.10 - @ResponseHeader

The @ResponseHeader annotation can be applied to @RestMethod-annotated parameters to denote them as an HTTP response headers.

  • ResponseHeader
    • _default - Default value if not present.
    • _enum - Output validation. Must match one of the values.
    • $ref - Schema reference.
    • api - Free-form Swagger JSON.
    • code - HTTP status codes that this header applies to.
    • collectionFormat - How collections of items are formatted.
    • description - Description.
    • example - Serialized example.
    • exclusiveMaximum - Output validation. Whether maximum is exclusive.
    • exclusiveMinimum - Output validation. Whether minimum is exclusive.
    • format - The schema type format.
    • items - The schema of items in a collection.
    • maximum - Output validation. Maximum numeric value.
    • maxItems - Output validation. Maximum number of items in a collection.
    • maxLength - Output validation. Maximum length of a string.
    • minimum - Output validation. Minimum numeric value.
    • minItems - Output validation. Minimum number of items in a collection.
    • minLength - Output validation. Minimum length of a string.
    • multipleOf - Output validation. Number must be a multiple of.
    • name - Header name.
    • pattern - Output validation. Must match regular expression.
    • serializer - Override the part serializer.
    • type - The schema type.
    • uniqueItems - Output validation. Collections must contain unique items only.
    • value - Free-form Swagger JSON.

This annotation can only be applied to parameters of type Value.

The following examples show 3 different ways of accomplishing the same task of setting an HTTP header on a response:

// Example #1 - Setting header directly on RestResponse object. @RestMethod(...) public void login(RestResponse res) { res.setHeader("X-Rate-Limit", 1000); ... } // Example #2 - Use on parameter. @RestMethod(...) public void login( @ResponseHeader( name="X-Rate-Limit", type="integer", format="int32", description="Calls per hour allowed by the user.", example="123" ) Value<Integer> rateLimit ) { rateLimit.set(1000); ... } // Example #3 - Use on type. @RestMethod(...) public void login(Value<RateLimit> rateLimit) { rateLimit.set(new RateLimit()); ... } @ResponseHeader( name="X-Rate-Limit", type="integer", format="int32", description="Calls per hour allowed by the user.", example="123" ) public class RateLimit { // OpenApiSerializer knows to look for this method based on format/type. public Integer toInteger() { return 1000; } }

Swagger documentation

The attributes on this annotation are also used to populate the generated Swagger for the method.
For example, in the case of the X-Rate-Limit example above, the following Swagger is generated:

'/user/login': { get: { responses: { 200: { headers: { 'X-Rate-Limit': { type: 'integer', format: 'int32', description: 'Calls per hour allowed by the user.', example: '123' } } } } } }

7.10.11 - @ResponseStatus

The @ResponseStatus annotation annotation can be applied to @RestMethod-annotated parameters to denote them as an HTTP response status codes.

This can only be applied to parameters of the Value class with an Integer type.

Examples:

// Defined on parameter. @RestMethod(name="GET", path="/user/login") public void login( @FormData("username") String username, @FormData("password") String password, @ResponseStatus Value<Integer> status ) { if (! isValid(username, password)) status.set(401); }

7.11 - Handling Form Posts

The best way to handle a form post is usually by using an input bean.
The following is a class that takes in URL-Encoded form post of the form "aString=foo&aNumber=123&aDate=2001-07-04T15:30:45Z".

@RestResource( path="/urlEncodedForm" ) public class UrlEncodedFormResource extends BasicRestServlet { /** POST request handler */ @RestMethod(name=POST, path="/") public Object doPost(@Body FormInputBean input) throws Exception { // Just mirror back the request return input; } public static class FormInputBean { public String aString; public int aNumber; @BeanProperty(pojoSwaps=CalendarSwap.ISO8601DT.class) public Calendar aDate; } }

Another possibility is to access the form parameters individually:

/** POST request handler */ @RestMethod(name=POST, path="/") public Object doPost(@FormData("aString") String aString, @FormData("aNumber") int aNumber, @FormData("aDate") Calendar aDate) throws Exception { ... }

The advantage to the form input bean is that it can handle any of the parsable types (e.g. JSON, XML...) in addition to URL-Encoding.
The latter approach only supports URL-Encoding.

  • If you're using form input beans, DO NOT use the @FormData attribute or ServletRequestWrapper.getParameter(String) method since this will cause the underlying JEE servlet to parse the HTTP body as a form post.
    Your input bean will end up being null since there won't be any content left after the servlet has parsed the body of the request.
    This applies to WHENEVER you use @Body or RestRequest.getBody()

7.12 - Handling Multi-Part Form Posts

The Juneau framework does not natively support multipart form posts.
However, it can be done in conjunction with the Apache Commons File Upload library.

The following is an example that uses the File Upload library to allow files to be uploaded as multipart form posts.

Example:

@RestResource( path="/tempDir" ) public class TempDirResource extends DirectoryResource { /** * [POST /upload] - Upload a file as a multipart form post. * Shows how to use the Apache Commons ServletFileUpload class for handling multi-part form posts. */ @RestMethod(name=POST, path="/upload", matchers=TempDirResource.MultipartFormDataMatcher.class) public Redirect uploadFile(RestRequest req) throws Exception { ServletFileUpload upload = new ServletFileUpload(); FileItemIterator iter = upload.getItemIterator(req); while (iter.hasNext()) { FileItemStream item = iter.next(); if (item.getFieldName().equals("contents")) { File f = new File(getRootDir(), item.getName()); IOPipe.create(item.openStream(), new FileOutputStream(f)).closeOut().run(); } } return new Redirect(); // Redirect to the servlet root. } /** Causes a 404 if POST isn't multipart/form-data */ public static class MultipartFormDataMatcher extends RestMatcher { @Override /* RestMatcher */ public boolean matches(RestRequest req) { String contentType = req.getContentType(); return contentType != null && contentType.startsWith("multipart/form-data"); } }

7.13 - Serializers

REST resources use the Serializer API for defining serializers for serializing response POJOs.

The servlet will pick which serializer to use by matching the request Accept header with the media types defined through the Serializer.getMediaTypeRanges() method.

Serializers can be associated with REST servlets in the following ways:

The following are all equivalent ways of defining serializers used by a resource:

// Option #1 - Defined via annotation. @RestResource(serializers={JsonSerializer.class, XmlSerializer.class}) public class MyResource { // Option #2 - Defined via builder passed in through resource constructor. public MyResource(RestContextBuilder builder) throws Exception { // Using method on builder. builder.serializers(JsonSerializer.class, XmlSerializer.class); // Same, but use pre-instantiated parsers. builder.serializers(JsonSerializer.DEFAULT, XmlSerializer.DEFAULT); // Same, but using property. builder.set(REST_serializers, JsonSerializer.class, XmlSerializer.class); } // Option #3 - Defined via builder passed in through init method. @RestHook(INIT) public void init(RestContextBuilder builder) throws Exception { builder.serializers(JsonSerializer.class, XmlSerializer.class); } // Override at the method level. @RestMethod(serializers={HtmlSerializer.class}) public MyPojo myMethod() { // Return a POJO to be serialized. return new MyPojo(); } }

See Also:

7.14 - Parsers

REST resources use the Parser API for defining parsers for parsing request body content and converting them into POJOs.

The servlet will pick which parser to use by matching the request Content-Type header with the media types defined through the Parser.getMediaTypes() method.

Parsers can be associated with REST servlets in the following ways:

The following are all equivalent ways of defining parsers used by a resource:

// Option #1 - Defined via annotation. @RestResource(parsers={JsonParser.class, XmlParser.class}) public class MyResource { // Option #2 - Defined via builder passed in through resource constructor. public MyResource(RestContextBuilder builder) throws Exception { // Using method on builder. builder.parsers(JsonParser.class, XmlParser.class); // Same, but use pre-instantiated parsers. builder.parsers(JsonParser.DEFAULT, XmlParser.DEFAULT); // Same, but using property. builder.set(REST_parsers, JsonParser.class, XmlParser.class); } // Option #3 - Defined via builder passed in through init method. @RestHook(INIT) public void init(RestContextBuilder builder) throws Exception { builder.parsers(JsonParser.class, XmlParser.class); } // Override at the method level. @RestMethod(parsers={HtmlParser.class}) public Object myMethod(@Body MyPojo myPojo) { // Do something with your parsed POJO. } }

See Also:

7.15 - Properties

As shown in previous sections, Juneau serializers and parsers are highly-configurable through properties. (See Configurable Properties)

These properties can be defined for serializers and parsers registered on a REST resource via the following:

Example:

import static org.apache.juneau.BeanContext.*; import static org.apache.juneau.serializer.Serializer.*; import static org.apache.juneau.json.JsonSerializer.*; // Servlet with properties applied @RestResource( properties={ // Bean properties should be sorted alphabetically. @Property(name=BEAN_sortProperties, value="true"), // Nulls should not be serialized @Property(name=SERIALIZER_trimNulls, value="true"), // Solidus characters should be escaped in JSON @Property(name=JSON_escapeSolidus, value="true") } ) public MyRestServlet extends BasicRestServlet {...}

The programmatic equivalent to this is:

// Servlet with properties applied @RestResource(...) public MyRestServlet extends BasicRestServlet { public MyRestServlet(RestContextBuilder builder) { builder .sortProperties(); // Note: RestContextBuilder extends from BeanContextBuilder .set(SERIALIZER_trimNulls, true); .set(JSON_escapeSolidus, true); } }

Properties can also be overridden at the Java method level:

// GET method with method-level properties @RestMethod( name=GET, path="/*", properties={ // Bean properties should be sorted alphabetically. @Property(name=BEAN_sortProperties, value="true"), // Nulls should not be serialized @Property(name=SERIALIZER_trimNulls, value="true"), // Solidus characters should be escaped in JSON @Property(name=JSON_escapeSolidus, value="true") } public Object doGet() { ... }

Using the RequestProperties object:

// Access it from RestRequest. public Object doGet(RestRequest req) { RequestProperties properties = req.getProperties(); properties.put(JSON_escapeSolidus, true); } // Or just pass in a RequestProperties object. public Object doGet(RequestProperties properties) { properties.put(JSON_escapeSolidus, true); }

Properties set via RequestProperties are session-override properties that are passed in through SerializerSessionArgs and ParserSessionArgs and can only be used on configuration settings marked as Session property: true.

Properties are open-ended and can be used for other purposes.
They're made available through the following methods:

See Also:

7.16 - Transforms

The Juneau serializers and parsers can be configured on how to handle POJOs through the use of Transforms. (See Transforms)

Transforms are associated serializers and parsers registered on a REST resource via the following:

// Servlet with transforms applied @RestResource( pojoSwaps={ // Calendars should be serialized/parsed as ISO8601 date-time strings CalendarSwap.DEFAULT_ISO8601DT.class, // Byte arrays should be serialized/parsed as BASE64-encoded strings ByteArrayBase64Swap.class }, beanFilters={ // Subclasses of MyInterface will be treated as MyInterface objects. // Bean properties not defined on that interface will be ignored. } ) public MyRestServlet extends BasicRestServlet {...}

The programmatic equivalent to this is:

// Servlet with properties applied @RestResource(...) public MyRestServlet extends BasicRestServlet { public MyRestServlet(RestContextBuilder builder) { builder .pojoSwaps( CalendarSwap.DEFAULT_ISO8601DT.class, ByteArrayBase64Swap.class ) .beanFilters(MyInterface.class); } }

7.17 - URIs

As mention earlier here, Juneau serializers have sophisticated support for transforming relative URIs to absolute form.

The following example shows a REST method that returns a list of URIs of various forms:

@RestResource( uriAuthority="http://foo.com:123", uriContext="/myContext" ) public class MyResource { @RestMethod public URI[] getURIs() { return new URI[] { URI.create("http://www.apache.org/f1a"), URI.create("/f1b"), URI.create("/f1c/x/y"), URI.create("f1d"), URI.create("f1e/x/y"), URI.create(""), URI.create("context:/f2a/x"), URI.create("context:/f2b"), URI.create("context:/"), URI.create("context:/.."), URI.create("servlet:/f3a/x"), URI.create("servlet:/f3b"), URI.create("servlet:/"), URI.create("servlet:/.."), URI.create("request:/f4a/x"), URI.create("request:/f4b"), URI.create("request:/"), URI.create("request:/..") }; } }

When requested as JSON, it produces the following result:

{ f1a:'http://www.apache.org/f1a', f1b:'http://foo.com:123/f1b', f1c:'http://foo.com:123/f1c/x/y', f1d:'http://foo.com:123/myContext/myServlet/f1d', f1e:'http://foo.com:123/myContext/myServlet/f1e/x/y', f1f:'http://foo.com:123/myContext/myServlet', f2a:'http://foo.com:123/myContext/f2a/x', f2b:'http://foo.com:123/myContext/f2b', f2c:'http://foo.com:123/myContext', f2d:'http://foo.com:123', f3a:'http://foo.com:123/myContext/myServlet/f3a/x', f3b:'http://foo.com:123/myContext/myServlet/f3b', f3c:'http://foo.com:123/myContext/myServlet', f3d:'http://foo.com:123/myContext', f4a:'http://foo.com:123/myContext/myServlet/myPath/f4a/x', f4b:'http://foo.com:123/myContext/myServlet/myPath/f4b', f4c:'http://foo.com:123/myContext/myServlet/myPath', f4d:'http://foo.com:123/myContext/myServlet' }

URI resolution is controlled by the following settings:

URIs are resolved by both regular and part serializers.

7.18 - Guards

Guards are classes that control access to REST classes and methods.

Guards are associated with resource classes and methods via the following:

// Define a guard that only lets Billy make a request public BillyGuard extends RestGuard { @Override /* RestGuard */ public boolean isRequestAllowed(RestRequest req) { return req.getUserPrincipal().getName().equals("Billy"); } } // Servlet with class-level guard applied @RestResource(guards=BillyGuard.class) public MyRestServlet extends BasicRestServlet { // Delete method that only Billy is allowed to call. @RestMethod(name="DELETE") public doDelete(RestRequest req, RestResponse res) throws Exception {...} }

A common use for guards is to only allow admin access to certain Java methods...

// DELETE method @RestMethod(name=DELETE, guards={AdminGuard.class}) public void doDelete(RestRequest req, RestResponse res) throws Exception {...}

public class AdminGuard extends RestGuard { @Override /* RestGuard */ public boolean isRequestAllowed(RestRequest req) { return req.getUserPrincipal().isUserInRole("ADMIN"); } }

A guard failure results in an HTTP 401 Unauthorized response.
However, this can be configured by overriding the RestGuard.guard(RestRequest,RestResponse) and processing the response yourself.

public class AdminGuard extends RestGuard { @Override /* RestGuard */ public boolean guard(RestRequest req, RestResponse res) throws RestException { if (! isOkay(req)) throw new RestException(SC_FORBIDDEN, "Access denied!!!"); return true; } }

When guards are associated at the class-level, it's equivalent to associating guards on all Java methods on the servlet.
If multiple guards are present, ALL guards must pass.

See Also:

7.19 - Converters

Converters can be thought of as "post-processors" for POJOs before they get passed to the serializers.

Converters are associated with resource classes and methods via the following:

Example:

// Associate the Traversable converter to all Java REST methods in this servlet @RestResource(converters=Traversable.class) public MyRestServlet extends BasicRestServlet { ... }

They can also be defined at the method level:

// GET person request handler. // Traversable conversion enabled to allow nodes in returned POJO tree to be addressed. // Queryable conversion enabled to allow returned POJO to be searched/viewed/sorted. @RestMethod( name=GET, path="/people/{id}/*", converters={Traversable.class,Queryable.class} ) public Person getPerson(@Path("id") int id) { return findPerson(id); }

The following converter is used to provide support for addressing child nodes in a POJO tree with URL path remainders.
In this code, the 3rd parameter is the object that was returned by the Java method.
The converter uses the PojoRest wrapper class to address nodes in the tree.

/** * Converter for enablement of PojoRest support on response objects returned by a @RestMethod method. * When enabled, objects in a POJO tree returned by the REST method can be addressed through additional URL path information. */ public class Traversable implements RestConverter { @Override /* RestConverter */ public Object convert(RestRequest req, Object o) throws RestException { if (o == null) return null; String pathRemainder = req.getPathMatch().getRemainder(); if (pathRemainder != null) { try { // Use the PojoRest class to traverse our POJO model. PojoRest p = new PojoRest(o); o = p.get(pathRemainder); } catch (PojoRestException e) { throw new RestException(e.getStatus(), e); } catch (Exception e) { throw new RestException(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, e); } } return o; } }

Juneau defines the following converters out-of-the-box:

  • RestConverter
    • Queryable
      Provides query parameters that can be used to transform the response (i.e. search/view/sort the POJO response before being serialized).
    • Traversable
      Allows nodes in the POJO response tree to be individually accessed through additional path info on the request.
    • Introspectable
      Allows method calls to be made on the response POJO, and for the result of that method call to be serialized as the response.
See Also:

7.20 - Messages

The @RestResource(messages) annotation is used to associate a resource bundle with a servlet class.

// Servlet with associated resource bundle @RestResource(messages="nls/MyMessages") public MyRestServlet extends BasicRestServlet { // Returns the localized greeting from the "greeting" key in MyMessages.properties @RestMethod(name=GET, path="/") public String printLocalizedGreeting(RestRequest req) { return req.getMessage("greeting"); }

The resource bundle can also be passed into the method by simply specifying a parameter of type ResourceBundle or MessageBundle:

@RestMethod(name=GET) public String printLocalizedGreeting(MessageBundle messages) { return messages.getString("greeting"); }

If a resource bundle is shared by multiple servlets, the label and description can be prefixed by the class name:

#-------------------------------------------------------------------------------- # Contents of MyMessages.properties #-------------------------------------------------------------------------------- greeting = Hello!

#-------------------------------------------------------------------------------- # Contents of shared MyMessages.properties #-------------------------------------------------------------------------------- MyRestServlet.greeting = Hello!

See Also:

7.21 - Encoders

The @RestResource(encoders) annotation can be used to associate character encoders with a servlet class.
Encoders can be used to enable various kinds of compression (e.g. "gzip") on requests and responses based on the request Accept-Encoding and Content-Encoding headers.

Example:

// Servlet with automated support for GZIP compression @RestResource(encoders={GzipEncoder.class}) public MyRestServlet extends BasicRestServlet { ... }

Juneau defines the following encoders out-of-the-box:

See Also:

7.22 - SVL Variables

In the previous examples, there were several cases where embedded variables were contained within annotation values:

@RestResource( title="$L{my.label}" )

Variables take the form $X{contents} where X can consist of zero or more ASCII characters and contents can be virtually anything.
This is called Simple Variable Language, or SVL, and is defined here: juneau-svl.

Features
  • Variables can be nested arbitrarily deep (e.g. "$X{$Y{foo}}").
  • Variables can contain arguments (e.g. "$L{my.label,arg1,arg2}").
  • Variables are recursively resolved.
    i.e., if a variable results to a value with another variable in it, that variable will also be resolved (restricted for security reasons on some variables).

Variables are configured on resources via the following API:

Example:

// Defined a variable that simply wrapps all strings inside [] brackets. // e.g. "$BRACKET{foobar}" -> "[foobar]" public class BracketVar extends SimpleVar { public BracketVar() { super("BRACKET"); } @Override /* Var */ public String resolve(VarResolverSession session, String arg) { return '[' + arg + ']'; } } // Register it with our resource. @RestResource(...) public class MyResource { public MyResource(RestContextBuilder builder) { builder.vars(BracketVar.class); } }

The methods involved with variables are:

There are two distinct groups of variables:

  • Initialization-time variables
    These are variables that can be used in many of the annotations in @RestResource.
    The RestContext.getVarResolver() method returns initialization-time variables only.
  • Request-time variables
    These are variables that are available during HTTP-requests and can be used on annotation such as @HtmlDoc.
    RestRequest.getVarResolverSession() method returns initialization and request-time variables.

The following is the default list of supported variables.

Default REST SVL Variables:
ModuleClassPatternInitialization
time
Request
time
Examples
juneau-svl EnvVariablesVar $E{key[,default]} yes yes $E{PATH}
SystemPropertiesVar $S{key[,default]} yes yes $S{java.home}
ArgsVar $A{key[,default]} yes yes $A{foo,null}
ManifestFileVar $MF{key[,default]} yes yes $MF{Main-Class}
IfVar $IF{arg,then[,else]} yes yes $IF{$S{my.boolean.property},foo,bar}
SwitchVar $SW{arg,p1:then1[,p2:then2...]} yes yes $SW{$P{os.name},*win*:Windows,*:Something else}
CoalesceVar $CO{arg1[,arg2...]} yes yes $CO{$S{my.property},$E{my.property},n/a}
PatternMatchVar $PM{arg,pattern} yes yes $PM{$P{os.name},*win*}
NotEmptyVar $NE{arg} yes yes $NE{$S{foo}}
UpperCaseVar $UC{arg} yes yes $UC{$S{foo}}
LowerCaseVar $LC{arg} yes yes $LC{$S{foo}}
juneau-config ConfigVar $C{key[,default]} yes yes $C{REST/staticFiles}
juneau-rest-server FileVar $F{path[,default]}} yes yes $F{resources/MyAsideMessage.html, Oops not found!}
ServletInitParamVar $I{name[,default]} yes yes $I{my.param}
LocalizationVar $L{key[,args...]} no yes $L{MyMessage,foo,bar}
RequestAttributeVar $RA{key1[,key2...]} no yes $RA{attrName}
RequestFormDataVar $RF{key1[,key2...]} no yes $RF{paramName}
RequestHeaderVar $RH{key1[,key2...]} no yes $RH{Header-Name}
RequestPathVar $RP{key1[,key2...]} no yes $RP{pathVAr}
RequestQueryVar $RQ{key1[,key2...]} no yes $RQ{paramName}
RequestVar $R{key1[,key2...]} no yes $R{contextPath}
RestInfoVar $RI{key} no yes $RI{externalDocs}
SerializedRequestAttrVar $SA{contentType,key[,default]} no yes $SA{application/json,$RA{foo}}
UrlVar $U{uri}> no yes $U{servlet:/foo}
UrlEncodeVar $UE{uriPart} yes yes $U{servlet:/foo?bar=$UE{$RA{bar}}
WidgetVar $W{name} no yes $W{MenuItemWidget}

7.23 - Configuration Files

The Server API provides methods for associating configuration files with REST servlets so that configuration properties can be defined in external files.

In recap, the Configuration API provides support for INI-style configuration files with embedded string variables:

Example:

#-------------------------- # Examples #-------------------------- [MyProperties] path = $E{PATH} javaHome = $S{java.home} customMessage = Java home is $C{MyProperties/javaHome} and the environment path is $C{MyProperties/path}.

These properties are then accessible through the Config class.

Config c = Config.create("myconfig.cfg").build(); String path = c.getString("MyProperties/path"); File javaHome = c.getObject("MyProperties/javaHome", File.class); String customMessage = c.getString("MyProperties/customMessage");

Configuration files are associated with REST resources through the following:

Example:

@RestResource( // Config file is located at ./config_dir/myconfig.cfg config="config_dir/myconfig.cfg", ... ) public class MyResource {...}

The annotation itself can contain string variables.
For example, the Microservice API BasicRestServlet class defines the location of the config file as a system property "juneau.configFile":

@RestResource( // Config file location is defined as a system property config="$S{juneau.configFile}", ... ) public class MyResource {...}

Once a config file has been associated with a REST resource, it can be accessed through the RestContextBuilder.getConfig() method.

A common usage is to use this method to initialize fields in your servlet.

@RestResource( // Config file is located at ./config_dir/myconfig.cfg config="config_dir/myconfig.cfg", ... ) public class MyResource { private final String path; private final File javaHome; public MyResource(RestContextBuilder builder) { Config c = builder.getConfig(); path = c.getString("MyProperties/path"); javaHome = c.getObject(File.class, "MyProperties/javaHome"); }

Another common usage is to refer to config properties through $C variables in your annotations:

@RestResource( // Get stylesheet from myconfig.cfg, but default to devops.css if it's not specified htmldoc=@HtmlDoc( stylesheet="$C{MyServlet/stylesheet,servlet:/styles/devops.css}", ) ... ) public class MyResource {...}

It's even possible to reference request-level variables in your config file if you use RestRequest.getConfig() to access the config file:

#------------------------------------- # Contents of config_dir/myconfig.cfg #------------------------------------- [HelloWorldResource] message = Hello $RQ{person}!

/** * Sample REST resource that prints out a simple "Hello world!" message. */ @RestResource( config="config_dir/myconfig.cfg", ... ) public class HelloWorldResource extends BasicRestServlet { /** * GET request handler. * Specify the GET parameter "?person=X" for a specialized message! */ @RestMethod(name=GET, path="/") public String sayHello(RestRequest req) { return req.getConfig().getString("HelloWorldResource/message"); } }

You can even add resource bundles into the mix:

#------------------------------------- # Contents of config_dir/myconfig.cfg #------------------------------------- [HelloWorldResource] message = $L{localizedMessage,$RQ{person}}

#------------------------------------------- # Contents of HelloWorldResource.properties #------------------------------------------- localizedMessage = Hello {0}!

/** * Sample REST resource that prints out a simple "Hello world!" message. */ @RestResource( messages="HelloWorldResources", config="config_dir/myconfig.cfg", ... ) public class HelloWorldResource extends BasicRestServlet { /** * GET request handler. * Specify the GET parameter "?person=X" for a specialized message! */ @RestMethod(name=GET, path="/") public String sayHello(RestRequest req) { return req.getConfig().getString("HelloWorldResource/message"); } }

See Also:

7.24 - Static files

The @RestResource(staticFiles) annotation is used to define paths and locations of statically-served files such as images or HTML documents.

The value is a JSON map of paths to packages/directories located on either the classpath or working directory.

Example:

package com.foo.mypackage; @RestResource( path="/myresource", staticFiles={"htdocs:docs"} ) public class MyResource extends BasicRestServlet {...}

Static files are found by calling Class.getResource(String) up the class hierarchy. If not found, then an attempt is made to find the class in the Java working directory.

In the example above, given a GET request to /myresource/htdocs/foobar.html, the servlet will attempt to find the foobar.html file in the following ordered locations:

  1. com.foo.mypackage.docs package.
  2. [working-dir]/docs directory.
Notes:
  • Mappings are cumulative from parent to child.
    Child resources can override mappings made on parent resources.
  • The media type on the response is determined by the RestContext.getMediaTypeForName(String) method.
See Also:

7.25 - Client Versioning

Client version headers are used to support backwards compatibility for breaking REST interface changes.
Using them, you're able to return different responses based on which client is making a request.

The APIs involved with defining client version headers are:

Example:

// Option #1 - Defined via annotation resolving to a config file setting with default value. @RestResource(clientVersionHeader="Client-Version") public class MyResource { // Call this method if Client-Version is at least 2.0. // Note that this also matches 2.0.1. @RestMethod(name=GET, path="/foobar", clientVersion="2.0") public Object method1() { ... } // Call this method if Client-Version is at least 1.1, but less than 2.0. @RestMethod(name=GET, path="/foobar", clientVersion="[1.1,2.0)") public Object method2() { ... } // Call this method if Client-Version is less than 1.1. @RestMethod(name=GET, path="/foobar", clientVersion="[0,1.1)") public Object method3() { ... }

See Also:

7.26 - RestInfoProvider

The RestInfoProvider class is used to find the title and description for your resource and also generate the Swagger documentation.
It can be overridden to provide your own custom Swagger documentation.

The methods on this interface are:

The info provider in turn supplies the information returned by the following methods:

Info providers are registered through the following property:

While you can implement this interface from scratch, you may want to instead consider extending from the BasicRestInfoProvider class described next.

7.26.1 - BasicRestInfoProvider

The BasicRestInfoProvider class is the default implementation of the RestInfoProvider interface.

It finds and collects information gathered from the following locations:

  • Localized JSON Swagger files in the classpath.
  • Reflection.
  • Annotations.
  • Properties files.

The class itself is designed to be extended if you wish to rely mostly on the default behavior, but tweak certain aspects.

7.27 - Swagger

One of the most useful features of Juneau is the ability to generate Swagger-based OPTIONS pages for self-documenting designs (i.e. REST interfaces that document themselves).

As described previously, the PetStore example provides an example of auto-generated Swagger JSON:

Using SwaggerUI, we're able to render that JSON as a Swagger user interface:

7.27.1 - BasicRestServlet

Any subclass of BasicRestServlet gets an auto-generated Swagger UI when performing an OPTIONS request with Accept:text/html.

The underlying mechanics are simple. The BasicRestServlet.getOptions(RestRequest) method returns a Swagger bean consisting of information gathered from annotations and other sources. Then that bean is swapped for a SwaggerUI bean when rendered as HTML.

Here's the class that defines the behavior:

@RestResource( // Allow OPTIONS requests to be simulated using ?method=OPTIONS query parameter. allowedMethodParams="OPTIONS", ... ) public abstract class BasicRestServlet extends RestServlet implements BasicRestConfig { /** * [OPTIONS /*] - Show resource options. * * @param req The HTTP request. * @return A bean containing the contents for the OPTIONS page. */ @RestMethod(name=OPTIONS, path="/*", summary="Swagger documentation", description="Swagger documentation for this resource.", htmldoc=@HtmlDoc( // Override the nav links for the swagger page. navlinks={ "back: servlet:/", "json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true" }, // Never show aside contents of page inherited from class. aside="NONE" ), // POJO swaps to apply to all serializers/parsers. pojoSwaps={ // Use the SwaggerUI swap when rendering Swagger beans. // This is a per-media-type swap that only applies to text/html requests. SwaggerUI.class }, // Properties to apply to all serializers/parsers and REST-specific API objects. properties={ // Add descriptions to the following types when not specified: @Property(name=JSONSCHEMA_addDescriptionsTo, value="bean,collection,array,map,enum"), // Add x-example to the following types: @Property(name=JSONSCHEMA_addExamplesTo, value="bean,collection,array,map"), // Don't generate schema information on the Swagger bean itself or HTML beans. @Property(name=JSONSCHEMA_ignoreTypes, value="Swagger,org.apache.juneau.dto.html5.*") }, // Shortcut for boolean properties. flags={ // Use $ref references for bean definitions to reduce duplication in Swagger. JSONSCHEMA_useBeanDefs } ) public Swagger getOptions(RestRequest req) { // Localized Swagger for this resource is available through the RestRequest object. return req.getSwagger(); } }

Note that to have your resource create Swagger UI, you must either extend from BasicRestServlet or provide your own @RestMethod-annotated method that returns a Swagger object and a SwaggerUI swap.

7.27.2 - Basic Swagger Info

Let's look at the various parts of the Petstore application Swagger UI to see how they are defined.

The top part of the page shows general information about the REST interface:

The information is pulled from the @RestResource(swagger) annotation.

org.apache.juneau.examples.rest.petstore.PetStoreResource

@RestResource( path="/petstore", title="Petstore application", ... swagger=@ResourceSwagger("$F{PetStoreResource.json}"), ... ) public class PetStoreResource extends BasicRestServletJena {...}

In this particular case, the Swagger is pulled in from a localized Swagger JSON file located in the org.apache.juneau.examples.rest.petstore package using the $F variable.

PetStoreResource.json

{ "swagger": "2.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", "termsOfService": "You are on your own.", "contact": { "name": "Juneau Development Team", "email": "dev@juneau.apache.org", "url": "http://juneau.apache.org" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "externalDocs": { "description": "Find out more about Juneau", "url": "http://juneau.apache.org" }, ... }

Note that the $F variable allows for request-locale-sensitive name matching so that you can provide localized Swagger information.

The $F variable simply expands to a string to fill the @ResourceSwagger(value) annotation. You could equivalently embed JSON directly into your annotation like so:

@RestResource( path="/petstore", title="Petstore application", ... swagger=@ResourceSwagger( // Raw Simplified JSON. // Values are concatenated. "{", "swagger: '2.0',", "version: '1.0.0',", ... "}" ), ... ) public class PetStoreResource extends BasicRestServletJena {...}

However, a more typical (and less error-prone) scenario is to define all of your Swagger as annotations:

@RestResource( path="/petstore", title="Petstore application", ... swagger=@ResourceSwagger( version="1.0.0", title="Swagger Petstore", termsOfService="You are on your own.", contact=@Contact( name="Juneau Development Team", email="dev@juneau.apache.org", url="http://juneau.apache.org" ), license=@License( name="Apache 2.0", url="http://www.apache.org/licenses/LICENSE-2.0.html" ), externalDocs=@ExternalDocs( description="Find out more about Juneau", url="http://juneau.apache.org" ) ), ... ) public class PetStoreResource extends BasicRestServletJena {...}

All annotations support SVL variables, so you could for example pull localized strings from resource bundles using $L variables.

@RestResource( path="/petstore", title="Petstore application", messages="nls/MyMessages", ... swagger=@ResourceSwagger( version="1.0.0", title="$L{myTitle}", termsOfService="$L{myTermsOfService}", contact=@Contact( name="$L{myTeam}", email="dev@juneau.apache.org", url="http://juneau.apache.org" ), license=@License( name="Apache 2.0", url="http://www.apache.org/licenses/LICENSE-2.0.html" ), externalDocs=@ExternalDocs( description="$L{myExternalDocsDescription}", url="http://juneau.apache.org" ) ), ... ) public class PetStoreResource extends BasicRestServletJena {...}

A third option is to define your Swagger information in your @RestResource(messages) resource bundle using predefined Swagger keywords:

PetStoreResource.version = 1.0.0 PetStoreResource.title = Swagger Petstore PetStoreResource.termsOfService = You are on your own. PetStoreResource.contact = {name:'Juneau Development Team', email:'dev@juneau.apache.org',...} PetStoreResource.license = {name:'Apache 2.0',...} PetStoreResource.externalDocs = {description:'Find out more about Juneau',...}

Information defined in multiple locations are merged into a single set of data. When the same information is provided in multiple locations, the following order-of-precedence is used:

  1. Java annotations
  2. Resource bundle
  3. Swagger JSON file

7.27.3 - Tags

Tags allow you to group operations into general categories. In the user interface, these can be expanded/collapsed by clicking on the tag sections.
In the example below, the pet and store tag sections are collapsed and the user section is not:

Tags are also defined in the @ResourceSwagger annotation

PetStoreResource.json

"tags": [ { "name": "pet", "description": "Everything about your Pets", "externalDocs": { "description": "Find out more", "url": "http://juneau.apache.org" } }, { "name": "store", "description": "Access to Petstore orders" }, { "name": "user", "description": "Operations about user", "externalDocs": { "description": "Find out more about our store", "url": "http://juneau.apache.org" } } ],

The annotation-only approach is shown here:

org.apache.juneau.examples.rest.petstore.PetStoreResource

swagger=@ResourceSwagger( ... tags={ @Tag( name="pet", description="Everything about your Pets", externalDocs=@ExternalDocs( description="Find out more", url="http://juneau.apache.org" ) ), @Tag( name="store", description="Access to Petstore orders" ), @Tag( name="user", description="Operations about user", externalDocs=@ExternalDocs( description="Find out more about our store", url="http://juneau.apache.org" ) ) } ),

Tags are associated with operations using the @MethodSwagger(tags) annotation:

GET /user operation

@RestMethod( name=GET, path="/user", summary="Petstore users", swagger=@MethodSwagger( tags="user" ) ) public Collection<User> getUsers() throws NotAcceptable {...}

Operations can be mapped to multiple tags.

Tags are optional. Operations not mapped to tags are listed in the UI before tagged operations.

For example, the getTopPage() method in PetStoreResource is not tagged, as well as the getOptions() method inherited from BaseRestServlet, so these show up at the top of the page:

7.27.4 - Operations

@RestMethod-annotated methods automatically get rendered as Swagger operations:

The following shows the annotations defined on the GET /pet operation:

PetStoreResource.getPets()

@RestMethod( name=GET, path="/pet", summary="All pets in the store", swagger=@MethodSwagger( tags="pet", ... ), ... ) public Collection<Pet> getPets() throws NotAcceptable { return store.getPets(); }

Methods marked as deprecated will show up as deprecated in the Swagger UI:

PetStoreResource.findPetsByTag()

@RestMethod( name=GET, path="/pet/findByTags", summary="Finds Pets by tags", ... ) @Deprecated public Collection<Pet> findPetsByTags(...) { ... }

7.27.5 - Parameters

Expanding operations shows you a list of parameters:

Parameter information can be defined in a couple of ways. The typical way is through annotations on parameters being passed to your @RestMethod-annotated method, like so:

@RestMethod( ... ) public Collection<Pet> getPets( @Query( name="s", description={ "Search.", "Key/value pairs representing column names and search tokens.", "'*' and '?' can be used as meta-characters in string fields.", "'>', '>=', '<', and '<=' can be used as limits on numeric and date fields.", "Date fields can be matched with partial dates (e.g. '2018' to match any date in the year 2018)." }, type="array", collectionFormat="csv", example="Bill*,birthDate>2000" ) String[] s, @Query( name="v", description={ "View.", "Column names to display." }, type="array", collectionFormat="csv", example="name,birthDate" ) String[] v, ... ) throws NotAcceptable { ... }

Note: The type and collectionFormat values above are optional and auto-detected based on the parameter class type if omitted. They're included here for clarity.
The examples will be explained in the next section.

Another option is to specify your parameter information in the parameters annotation as free-form Simple JSON.
In the case of the PetStoreResource.getPets() method, we pull this information from a static field defined in the Queryable class:

PetStoreResource.getPets()

@RestMethod( name=GET, path="/pet", summary="All pets in the store", swagger=@MethodSwagger( tags="pet", parameters={ Queryable.SWAGGER_PARAMS } ), ... converters={Queryable.class} ) public Collection<Pet> getPets() throws NotAcceptable { return store.getPets(); }

Queryable

public class Queryable implements RestConverter { public static final String SWAGGER_PARAMS="" + "{" + "in:'query'," + "name:'s'," + "description:'" + "Search.\n" + "Key/value pairs representing column names and search tokens.\n" + "\\'*\\' and \\'?\\' can be used as meta-characters in string fields.\n" + "\\'>\\', \\'>=\\', \\'<\\', and \\'<=\\' can be used as limits on numeric and date fields.\n" + "Date fields can be matched with partial dates (e.g. \\'2018\\' to match any date in the year 2018)." + "'," + "type:'array'," + "collectionFormat:'csv'," + "x-examples:{example:'?s=Bill*,birthDate>2000'}" + "}," + "{" + "in:'query'," + "name:'v'," + "description:'" + "View.\n" + "Column names to display." + "'," + "type:'array'," + "collectionFormat:'csv'," + "x-examples:{example:'?v=name,birthDate'}" + "}," ... ; }

This information could have also been defined in the Swagger JSON for the resource as well.

The parameter section contains information about the request body as well for PUT and POST methods, as shown here:

The definition of this method is shown here:

@RestMethod( summary="Add a new pet to the store", swagger=@MethodSwagger( tags="pet" ) ) public Ok postPet( @Body(description="Pet object to add to the store") PetCreate pet ) throws IdConflict, NotAcceptable, UnsupportedMediaType { store.create(pet); return OK; }

Note that the schema information on the body parameter is automatically detected if not provided.

7.27.6 - Parameter Examples

The model select box in the parameters can be expanded to show examples:

The examples for query/form-data/path/header parameters can be defined using the example attribute on your annotated parameters as shown here:

@RestMethod( ... ) public Collection<Pet> getPets( @Query( name="s", description={ "Search.", "Key/value pairs representing column names and search tokens.", "'*' and '?' can be used as meta-characters in string fields.", "'>', '>=', '<', and '<=' can be used as limits on numeric and date fields.", "Date fields can be matched with partial dates (e.g. '2018' to match any date in the year 2018)." }, type="array", collectionFormat="csv", example="Bill*,birthDate>2000" ) ... ) throws NotAcceptable { ... }

This value gets converted to an x-examples attribute in your parameter information:

{ "swagger": "2.0", "paths": { "/pet": { "get": { "operationId": "getPets", "summary": "All pets in the store", "parameters": [ { "in": "query", "name": "s", ... "x-examples": { "example": "?s=Bill*,birthDate>2000" } }, ...

Examples for request bodies includes all supported Content-Type values:

These are based on the parsers registered on your servlet or method.

Selecting any of the content types shows you a representative example for the POJO:

There are several options for defining examples for request bodies:

  • @Body(example) annotation.
  • @Body(examples) annotation.
  • Defining an "x-examples" field in the inherited Swagger JSON body field (classpath file or @ResourceSwagger(value)/@MethodSwagger(value)).
  • Defining an "x-examples" field in the Swagger Schema Object for the body (including referenced "$ref" schemas).
  • Allowing Juneau to auto-generate a code example.

When using @Body(example), you specify a Simple JSON representation of your POJO. The Swagger generator will then convert that JSON into a POJO using the registered serializers on the REST method to produce examples for all supported language types.

Example:

// A JSON representation of a PetCreate object. @Body( example="{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}" )

The @Body(examples) annotation allows you to specify raw output values per media type. This field allows you to override the behavior and show examples for only specified media types or different examples for different media types.

Example:

// A JSON representation of a PetCreate object. @Body( examples={ "'application/json':'{name:\\'Doggie\\',species:\\'Dog\\'}',", "'text/uon':'(name:Doggie,species=Dog)'" } )

The Swagger generator uses these to create an x-examples entry in your generated Swagger:

"/pet": { "post": { "operationId": "postPet", "summary": "Add a new pet to the store", "parameters": [ { "in": "body", "description": "Pet object to add to the store", "required": true, "schema": { "$ref": "#/definitions/PetCreate" }, "x-examples": { "application/json": "{\n\t\"name\": \"Doggie\",\n\t\"species\": \"Dog\",\n\t\"price\": 9.99,\n\t\"tags\": [\n...", "application/json+simple": "{\n\tname: 'Doggie',\n\tspecies: 'Dog',\n\tprice: 9.99,\n\ttags: [\n\t\t'friendly...", "text/xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<object>\n\t<name>Doggie</name&...", "text/html+stripped": "<table>\n\t<tr>\n\t\t<td>name</td>\n\t\t<td>Doggie</t...", "text/uon": "(\n\tname=Doggie,\n\tspecies=Dog,\n\tprice=9.99,\n\ttags=@(\n\t\tfriendly,\n\t\tcute\n\t)\n)", "application/x-www-form-urlencoded": "name=Doggie\n&species=Dog\n&price=9.99\n&tags=@(\n\tfriendly,\n\tcute\n)", "text/openapi": "(\n\tname=Doggie,\n\tspecies=Dog,\n\tprice=9.99,\n\ttags=@(\n\t\tfriendly,\n\t\tcute\n\t)\n)", "octal/msgpack": "84 A4 6E 61 6D 65 A6 44 6F 67 67 69 65 A7 73 70 65 63 69 65 73 A3 44 6F 67 A5 70 72 69 63 6...", "text/plain": "{name:'Doggie',species:'Dog',price:9.99,tags:['friendly','cute']}", "text/xml+rdf": "<rdf:RDF\n xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\n xmlns:j=\"ht...", "text/turtle": "@prefix jp: <http://www.apache.org/juneaubp/> .\n@prefix j: <http://www.a...", "text/n-triple": "_:A59722791X3aX165d321a2b4X3aXX2dX7fca <http://www.apache.org/juneaubp/name> \"Doggie...", "text/n3": "@prefix jp: <http://www.apache.org/juneaubp/> .\n@prefix j: <http://www.apach..." } } ],

Another option is to define these directly in your resource Swagger JSON file, or via @RestResource(swagger)/@RestMethod(swagger).

Juneau also supports auto-generation of JSON-Schema directly from POJO classes.
By default, the generated swagger uses to the JSONSCHEMA_addExamplesTo setting to automatically add examples to beans, collections, arrays, and maps:

public abstract class BasicRestServlet extends RestServlet implements BasicRestConfig { @RestMethod(name=OPTIONS, path="/*", ... properties={ // Add x-example to the following types: @Property(name=JSONSCHEMA_addExamplesTo, value="bean,collection,array,map"), }, ... ) public Swagger getOptions(RestRequest req) {...}

Examples can be defined via static methods, fields, and annotations on the classes themselves.

Examples:

// Annotation on class. @Example("{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}") public class PetCreate { ... }

// Annotation on static method. public class PetCreate { @Example public static PetCreate sample() { return new PetCreate("Doggie", 9.99f, "Dog", new String[] {"friendly","cute"}); } }

// Static method with specific name 'example'. public class PetCreate { public static PetCreate example() { return new PetCreate("Doggie", 9.99f, "Dog", new String[] {"friendly","cute"}); } }

// Static field. public class PetCreate { @Example public static PetCreate EXAMPLE = new PetCreate("Doggie", 9.99f, "Dog", new String[] {"friendly","cute"}); }

Examples can also be specified via generic properties as well using the BeanContext.BEAN_examples property at either the class or method level.

Example:

// Examples defined at class level. @RestResource( properties={ @Property( name=BEAN_examples, value="{'org.apache.juneau.examples.rest.petstore.PetCreate': {name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}}" ) } )

See Also:

7.27.7 - Responses

Under the input parameters are listed the possible responses for the resource:

The 200 response is determined by the return type on the method, in this case a collection of Pet objects:

@RestMethod( name=GET, path="/pet", summary="All pets in the store", ... ) public Collection<Pet> getPets() throws NotAcceptable { return store.getPets(); }

Note that additional responses can be specified by throwing exceptions annotated with the @Response annotation such as this one:

@Response(code=406, description="Not Acceptable") public class NotAcceptable extends RestException {...}

Like input parameters, the Swagger for responses can be define in multiple locations such as:

See Also:

7.27.8 - Response Examples

The model select box in the responses can be expanded to show examples:

PetStoreResource.getPet()

Examples are provided for any supported Accept type based on the serializers defined on your servlet/method.

application/json+simple
text/uon

Examples are pulled from the examples attribute in the response object of the generated Swagger JSON:

"/pet/{petId}": { "get": { "operationId": "getPet", "summary": "Find pet by ID", "description": "Returns a single pet", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/Pet" }, "examples": { "text/html+stripped": "<table>\n\t<tr>\n\t\t<td>id</td>\n\t\t<td>\t\t\t<a href=\"...", "text/html+schema": "<html>\n\t<head>\n\t\t<link rel='icon' href='$U{servlet:/htdocs/cat.png}'/>...", "application/json": "{\n\t\"id\": 123,\n\t\"species\": {\n\t\t\"name\": \"Dog\",\n\t\t\"id\": 123\n\t},\n\t\"name\...", "application/json+simple": "{\n\tid: 123,\n\tspecies: {\n\t\tname: 'Dog',\n\t\tid: 123\n\t},\n\tname: 'Doggie',\n\...", "application/json+schema": "{\n\t\"type\": \"object\",\n\t\"properties\": {\n\t\t\"id\": {\n\t\t\t\"type\": \"inte...", "text/xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Pet>\n\t<id>123</id>\n\t<spec...", "text/xml+schema": "<schema xmlns=\"http://www.w3.org/2001/XMLSchema\" targetNamespace=\"http://www.apache.org/...", "text/uon": "(\n\tid=123,\n\tspecies=(\n\t\tname=Dog,\n\t\tid=123\n\t),\n\tname=Doggie,\n\ttags=@(\n\t\t(\n\t\t\tn...", "application/x-www-form-urlencoded": "id=123\n&species=(\n\tname=Dog,\n\tid=123\n)\n&name=Doggie\n&tags=@(\n\t(\n\...", "text/openapi": "(\n\tid=123,\n\tspecies=(\n\t\tname=Dog,\n\t\tid=123\n\t),\n\tname=Doggie,\n\ttags=@(\n\t\t(\n\t\...", "octal/msgpack": "86 A2 69 64 7B A7 73 70 65 63 69 65 73 82 A4 6E 61 6D 65 A3 44 6F 67 A2 69 64 7B A4 6E 61 6D 65 ...", "text/xml+soap": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Envelope soap=\"http://www.w3.org/2003/05/...", "text/plain": "{id:123,species:{name:'Dog',id:123},name:'Doggie',tags:[{name:'MyTag',id:123}],price:0.0,status:'AV...", "text/xml+rdf": "<rdf:RDF\n xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\n xmlns:j=\"http://...", "text/xml+rdf+abbrev": "<rdf:RDF\n xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\n xmlns:j=\"...", "text/turtle": "@prefix jp: <http://www.apache.org/juneaubp/> .\n@prefix j: <http://www.apache...", "text/n-triple": "_:A720f0f4fX3aX165d4974933X3aXX2dX7f93 <http://www.apache.org/juneaubp/name> \"Dog\" .\n_:...", "text/n3": "@prefix jp: <http://www.apache.org/juneaubp/> .\n@prefix j: <http://www.apache.org..."

There are several options for defining examples for response bodies:

  • @Response(example) annotation.
  • @Response(examples) annotation.
  • Defining an "examples" field in the inherited Swagger JSON response object (classpath file or @ResourceSwagger(value)/@MethodSwagger(value)).
  • Defining an "examples" field in the Swagger Schema Object for the response object (including referenced "$ref" schemas).
  • Allowing Juneau to auto-generate a code example.

The @Response(example) annotation can be used on either your @RestMethod-annotated method or return class to define the example of the body.

// A JSON representation of a Pet object. @Response( example="{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}" )

This is a Simple JSON representation of the body that is converted to a POJO and then serialized to all the registered serializers on the REST method to produce examples for all supported language types. These values are then used to automatically populate the examples field.

Direct per-media-type examples can also be defined using the @Response(examples) annotation:

// A JSON representation of a PetCreate object. @Response( examples={ "'application/json':'{name:\\'Doggie\\',species:\\'Dog\\'}',", "'text/uon':'(name:Doggie,species=Dog)'" } )

Juneau also supports auto-generation of JSON-Schema directly from POJO classes.
By default, the generated swagger uses to the JSONSCHEMA_addExamplesTo setting to automatically add examples to beans, collections, arrays, and maps:

In particular, examples can be defined via static methods, fields, and annotations on the classes themselves.

// Annotation on class. @Example("{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}") public class PetCreate { ... }

// Annotation on static method. public class PetCreate { @Example public static PetCreate sample() { return new PetCreate("Doggie", 9.99f, "Dog", new String[] {"friendly","cute"}); } }

// Static method with specific name 'example'. public class PetCreate { public static PetCreate example() { return new PetCreate("Doggie", 9.99f, "Dog", new String[] {"friendly","cute"}); } }

// Static field. public class PetCreate { @Example public static PetCreate EXAMPLE = new PetCreate("Doggie", 9.99f, "Dog", new String[] {"friendly","cute"}); }

Examples can also be specified via generic properties as well using the BeanContext.BEAN_examples property at either the class or method level.

// Examples defined at class level. @RestResource( properties={ @Property( name=BEAN_examples, value="{'org.apache.juneau.examples.rest.petstore.PetCreate': {name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}}" ) } )

Response headers are also rendered in the Swagger UI:

These can be auto-generated from @ResponseHeader annotations defined on either method parameters or type classes.
The example above shows one of each:

@RestMethod( name=GET, path="/user/login", summary="Logs user into the system", swagger=@MethodSwagger( tags="user" ) ) public Ok login( @Query( name="username", description="The username for login", required=true, example="myuser" ) String username, @Query( name="password", description="The password for login in clear text", required=true, example="abc123" ) String password, @ResponseHeader( name="X-Rate-Limit", type="integer", format="int32", description="Calls per hour allowed by the user.", example="123" ) Value<Integer> rateLimit, Value<ExpiresAfter> expiresAfter, RestRequest req, RestResponse res ) throws InvalidLogin, NotAcceptable { if (! store.isValid(username, password)) throw new InvalidLogin(); Date d = new Date(System.currentTimeMillis() + 30 * 60 * 1000); req.getSession().setAttribute("login-expires", d); rateLimit.set(1000); expiresAfter.set(new ExpiresAfter(d)); return OK; }

@ResponseHeader( name="X-Expires-After", type="string", format="date-time", description="Date in UTC when token expires", example="2012-10-21" ) public static class ExpiresAfter { private final Calendar c; public ExpiresAfter(Date d) { this.c = new GregorianCalendar(); c.setTime(d); } public Calendar toCalendar() { return c; } }

7.27.9 - Models

The JsonSchemaGenerator.JSONSCHEMA_useBeanDefs setting can be used to reduce the size of your generated Swagger JSON files by creating model definitions for beans and referencing those definitions through $ref attributes.

By default, this flag is enabled when extending from BasicRestServlet:

public abstract class BasicRestServlet extends RestServlet implements BasicRestConfig { @RestMethod(name=OPTIONS, path="/*", ... flags={ // Use $ref references for bean definitions to reduce duplication in Swagger. JSONSCHEMA_useBeanDefs } ) public Swagger getOptions(RestRequest req) {...}

In the Swagger UI, this causes bean definitions to show up in the Models section at the bottom of the page:

Models section
Models section with Order bean expanded

In the generated Swagger JSON, embedded schema information for beans will be replaced with references such as the one shown below for the Order bean:

{ "swagger": "2.0", "paths": { "/store/order": { "get": { "operationId": "getOrders", "summary": "Petstore orders", "responses": { "200": { "description": "OK", "schema": { "description": "java.util.Collection<org.apache.juneau.examples.rest.petstore.Order>", "type": "array", "items": { "$ref": "#/definitions/Order" } }, ... ... ... ... ... }, "definitions": { "Order": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "petId": { "type": "integer", "format": "int64" }, "shipDate": { "type": "string" }, "status": { "type": "string", "enum": [ "PLACED", "APPROVED", "DELIVERED" ] } }, "description": "org.apache.juneau.examples.rest.petstore.Order", "example": { "id": 123, "petId": 456, "shipDate": "2012-12-21", "status": "APPROVED" } }, ... }

Note that this does not affect how the information is rendered for that bean in the Swagger UI:

7.27.10 - SwaggerUI.css

The look-and-feel of the Swagger UI is controlled via a single CSS file: SwaggerUI.css.

In the microservice template, this file is located in the files/htdocs/styles directory. It's a simple straightforward file consisting of less than 350 lines.
This file can be modified to change the look-and-feel of your Swagger UI.

7.28 - @HtmlDoc

The @HtmlDoc annotation is used to customize the HTML view of your serialized POJOs.
It's used in the following locations:

The annotation itself is just a convenience for setting configuration properties set on the HtmlDocSerializer class.
For example, the following two pieces of code are equivalent:

// Title defined via property. @RestResource( properties={ @Property(name=HTMLDOC_title, value="My Resource Page") } ) // Title defined via @HtmlDoc annotation. @RestResource( htmldoc=@HtmlDoc( title="My Resource Page" ) )

The purpose of these annotation is to populate the HTML document view which by default consists of the following structure:

<html> <head> <style type='text/css'> CSS styles and links to stylesheets </style> </head> <body> <header> Page header </header> <nav> Navigation links </nav> <aside> Side-bar text </aside> <article> Contents of serialized object </article> <footer> Footer message </footer> </body> </html>

The outline above is controlled by the HtmlDocTemplate interface which can be overridden via the @HtmlDoc(template) annotation.

The HelloWorldResource class was an example of the @HtmlDoc annotation in use:

/** * Sample REST resource that prints out a simple "Hello world!" message. */ @RestResource( path="/helloWorld", htmldoc=@HtmlDoc( navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS" }, aside={ "<div style='max-width:400px' class='text'>", " <p>This page shows a resource that simply response with a 'Hello world!' message</p>", " <p>The POJO serialized is a simple String.</p>", "</div>" } ) ) public class HelloWorldResource extends BasicRestServlet {...}

SVL variables can be used in any of these annotations:

@RestResource( path="/helloWorld", // Register a config file. config="MyConfig.cfg", htmldoc=@HtmlDoc( navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS", // Add a nav link to view the source code for this class. "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java" }, aside={ // Localize our messages. "<div style='max-width:400px' class='text'>", " <p>$L{localizedMessage1}</p>", " <p>$L{localizedMessage2}</p>", "</div>" } ) ) public class HelloWorldResource extends BasicRestServlet {...}

See Also:

7.28.1 - User Interfaces (UI) vs. Developer Interfaces (DI)

An important distinction needs to be made about the HTML representations produced by the REST API. These should not be considered User Interfaces, but rather Developer Interfaces.

UIs should hide the end-user from the underlying architecture. The audience generally consists of non-technical people not interested in how the UI works.

DIs, on the other hand, should NOT hide the end-user from the underlying architecture. Instead, it's a thin veneer over the REST interface with the following goals:

  • Make it easy for the developer to explore and understand the REST API.
  • Make it easy for the developer to debug the REST API using simple tools (hopefully just a browser).

As a result, the following guidelines are recommended:

  • Use titles/descriptions/asides to describe why the REST interface exists. A developer knowing little about it should be able to access it with a browser and quickly understand what it is and how to use it.
  • Don't hide the raw data! The HTML view should simply be considered an easier-to-read representation of the data normally rendered in JSON or some other format.
  • Limit your use of Javascript! You can use it sparingly if you want to implement something simple like a pull-down menu to simplify some debug task, but remember that your audience cares more about interacting with your service programmatically using REST. Remember that the HTML is just icing on the cake.
  • Don't use it to implement a Web 2.0 interface! If you want a Web 2.0 UI, implement it separately ON TOP OF this REST interface. The architecture is flexible enough that you could in theory pull in and use jQuery, React, Angular, or any number of sophisticated Javascript UI frameworks. Resist the urge to do so.

7.28.2 - Widgets

The Widget class allows you to add arbitrary HTML, CSS, and Javascript to HTML pages.
They are registered in the following locations:

Example:

@RestMethod( widgets={ MyWidget.class } htmldoc=@HtmlDoc( navlinks={ "$W{MyWidget}" }, aside={ "Check out this widget: $W{MyWidget}" } ) )

The Widget class is composed of the following methods:

The HTML content returned by the getHtml(RestRequest) method is added wherever the "$W{...}" variable is used.

The CSS returned by getScript(RestRequest) is added to the style section in the page header.

The Javascript returned by getScript(RestRequest) is added to the script section in the page header.

The following examples shows how to associate a widget with a REST method and then have it rendered in the links and aside section of the page.
It shows an example of a widget that renders an image located in the htdocs static files directory in your classpath (see @RestResource(staticFiles)):

public class MyWidget extends Widget { @Override /* Widget */ public String getHtml(RestRequest req) throws Exception { UriResolver r = req.getUriResolver(); // API used for resolving URIs. return "<img class='myimage' onclick='myalert(this)' src='"+r.resolve("servlet:/htdocs/myimage.png")+"'>"; } @Override /* Widget */ public String getScript(RestRequest req) throws Exception { return "" + "\n function myalert(imageElement) {" + "\n alert('cool!');" + "\n }"; } @Override /* Widget */ public String getStyle(RestRequest req) throws Exception { return "" + "\n .myimage {" + "\n border: 10px solid red;" + "\n }"; } }

The Widget class also defines the following two convenience methods for loading Javascript and CSS files from the classpath or file system.

Example:

public class MyWidget extends Widget { ... @Override /* Widget */ public String getScript(RestRequest req) throws Exception { return getClasspathResourceAsString("MyWidget.js"); } @Override /* Widget */ public String getStyle(RestRequest req) throws Exception { return getClasspathResourceAsString("MyWidget.css"); } }

See Also:

7.28.3 - Predefined Widgets

The org.apache.juneau.rest.widget package contains predefined reusable widgets.

MenuItemWidget

MenuItemWidget is an abstract class for rendering menu items with drop-downs. It defines some simple CSS and Javascript for enabling drop-down menus in the nav section of the page (although nothing keeps you from using it in an arbitrary location in the page).

The script specifies a "menuClick(element)" function that toggles the visibility of the next sibling of the element.

Subclasses implement the following two methods:

For example, to render a link that brings up a simple dialog in a div tag:

@Override public String getLabel() { return "my-menu-item"; }; @Override public Div getLabel() { return Html5Builder.div("Surprise!").style("color:red"); };

The HTML content returned by the getHtml(RestRequest) method is added where the "$W{...}" is referenced in the page.

ContentTypeMenuItem

ContentTypeMenuItem is a predefined Widget that returns back a list of hyperlinks for rendering the contents of a page in a variety of content types.

The variable it resolves is "$W{ContentTypeMenuItem}".

An example of this widget can be found in the PetStoreResource in the examples that provides a drop-down menu item for rendering all other supported content types in plain text:

@RestMethod( name=GET, path="/", widgets={ ContentTypeMenuItem.class, }, htmldoc=@HtmlDoc( navlinks={ "up: ...", "options: ...", "$W{QueryMenuItem}", "$W{ContentTypeMenuItem}", "$W{ThemeMenuItem}", "source: ..." } ) ) public Collection<Pet> getPets() {

It renders the following popup-box:

QueryMenuItem

QueryMenuItem is a predefined Widget that returns a menu-item drop-down form for entering search/view/sort arguments.

The variable it resolves is "$W{QueryMenuItem}".

This widget is designed to be used in conjunction with the Queryable converter, although implementations can process the query parameters themselves if they wish to do so by using the RequestQuery.getSearchArgs() method to retrieve the arguments and process the data themselves.

An example of this widget can be found in the PetStoreResource in the examples that provides search/view/sort capabilities against the collection of POJOs:

@RestMethod( name=GET, path="/", widgets={ QueryMenuItem.class, }, htmldoc=@HtmlDoc( navlinks={ "up: ...", "options: ...", "$W{QueryMenuItem}", "$W{ContentTypeMenuItem}", "$W{ThemeMenuItem}", "source: ..." } ), converters=Queryable.class ) public Collection<Pet> getPets() {

It renders the following popup-box:

Tooltips are provided by hovering over the field names.

When submitted, the form submits a GET request against the current URI with special GET search API query parameters. (e.g. "?s=column1=Foo*&v=column1,column2&o=column1,column2-&p=100&l=100"). The Queryable class knows how to perform these filters against collections of POJOs.

ThemeMenuItem

ThemeMenuItem is a predefined Widget that returns back a list of hyperlinks for rendering the contents of a page in the various default styles.

The variable it resolves is "$W{ThemeMenuItem}".

An example of this widget can be found in the PetStoreResource in the examples that provides a drop-down menu item for rendering all other supported content types in plain text:

@RestMethod( name=GET, path="/", widgets={ ThemeMenuItem.class, }, htmldoc=@HtmlDoc( navlinks={ "up: ...", "options: ...", "$W{QueryMenuItem}", "$W{ContentTypeMenuItem}", "$W{ThemeMenuItem}", "source: ..." } ) ) public Collection<Pet> getPets() {

PoweredByJuneau

PoweredByJuneau is a predefined Widget that places a powered-by-Juneau message on a page.

The variable it resolves is "$W{PoweredByJuneau}".

It produces a simple Apache Juneau icon floating on the right. Typically it's used in the footer of the page, as shown below in the AddressBookResource from the examples:

@RestResource( path="/addressBook", widgets={ PoweredByJuneau.class }, htmldoc=@HtmlDoc( footer="$W{PoweredByJuneau}" )

It renders the following image:

Tooltip

Tooltip is a predefined template for adding tooltips to HTML5 bean constructs, typically in menu item widgets.

The following examples shows how tooltips can be added to a menu item widget.

public class MyFormMenuItem extends MenuItemWidget { @Override public String getLabel(RestRequest req) throws Exception { return "myform"; } @Override public Object getContent(RestRequest req) throws Exception { return div( form().id("form").action("servlet:/form").method(POST).children( table( tr( th("Field 1:"), td(input().name("field1").type("text")), td(new Tooltip("(?)", "This is field #1!", br(), "(e.g. '", code("Foo"), "')")) ), tr( th("Field 2:"), td(input().name("field2").type("text")), td(new Tooltip("(?)", "This is field #2!", br(), "(e.g. '", code("Bar"), "')")) ) ) ) ); } }

7.28.4 - UI Customization

The HTML views of POJOs can somewhat be considered a rudimentary User Interface. In reality, a better term for them would be a Developer Interface as they're meant to be used primarily by developers and not end users. Despite that distinction, it is possible to 'brand' the HTML page to whatever you desire.

The sample root page below includes some default branding for Juneau and Apache:

http://localhost:10000/helloWorld

The Juneau REST framework does not provide specific branding support (i.e. there is no concept of a brand icon). Instead, it just uses the existing open-ended API for defining branding via annotations on your REST classes.

@RestResource( ... // HTML-page specific settings htmldoc=@HtmlDoc( // Default page header contents. header={ "<h1>$R{resourceTitle}</h1>", // Use @RestResource(title) "<h2>$R{methodSummary,resourceDescription}</h2>", // Use either @RestMethod(summary) or @RestResource(description) "$C{REST/header}" // Extra header HTML defined in external config file. }, // 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). stylesheet="$C{REST/theme,servlet:/htdocs/themes/devops.css}", // Default contents to add to the <head> section of the HTML page. // Use it to add a favicon link to the page. head={ "<link rel='icon' href='$U{$C{REST/favicon}}'/>" }, // No default page footer contents. // Can be overridden from external config file. footer="$C{REST/footer}" ), // Optional external configuration file. config="$S{juneau.configFile}", // 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. staticFiles="$C{REST/staticFiles}" ) public interface BasicRestConfig {}

@RestResource( ... htmldoc=@HtmlDoc( htmldoc=@HtmlDoc( // Basic page navigation links. navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS" } ) ), ... ) public abstract class BasicRestServlet extends RestServlet implements BasicRestConfig {...}

@RestResource public abstract class BasicRestServletGroup extends BasicRestServlet {...}

@RestResource( htmldoc=@HtmlDoc( widgets={ ContentTypeMenuItem.class, ThemeMenuItem.class }, navlinks={ "options: ?method=OPTIONS", "$W{ContentTypeMenuItem}", "$W{ThemeMenuItem}", "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java" }, aside={ "<div style='max-width:400px' class='text'>", " <p>This is an example of a 'router' page that serves as a jumping-off point to child resources.</p>", " <p>Resources can be nested arbitrarily deep through router pages.</p>", " <p>Note the <span class='link'>options</span> link provided that lets you see the generated swagger doc for this page.</p>", " <p>Also note the <span class='link'>sources</span> link on these pages to view the source code for the page.</p>", " <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>", " <p>Other features (such as this aside) are added through annotations.</p>", "</div>" } ), ... ) public class RootResources extends BasicRestServletGroup {...}

The default annotation values use $C variables to pull in values from an optional external configuration file such as the one shown below:

#======================================================================================================================= # REST settings #======================================================================================================================= [REST] staticFiles = htdocs:files/htdocs # Stylesheet to use for HTML views. theme = servlet:/htdocs/themes/devops.css headerIcon = servlet:/htdocs/images/juneau.png headerLink = http://juneau.apache.org footerIcon = servlet:/htdocs/images/asf.png footerLink = http://www.apache.org favicon = $C{REST/headerIcon} header = <a href='$U{$C{REST/headerLink}}'> <img src='$U{$C{REST/headerIcon}}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/> </a> footer = <a href='$U{$C{REST/footerLink}}'> <img src='$U{$C{REST/footerIcon}}' style='float:right;padding-right:20px;height:32px'/> </a>

The take-away here is that the "User Interface" is open-ended, lets you define pretty much anything you want through arbitrary HTML, and allows you either hardcode your interface inside annotations or pull them in via string variables from other places such as external config files.

See Also:

7.28.5 - Stylesheets

The sample root page renders in the default "devops" look-and-feel:

http://localhost:10000

The sample root page provides a dropdown widget to try out the other default look-and-feels:

For example, the "light" look-and-feel:

http://localhost:10000/?stylesheet=styles%2Flight.css

And the "dark" look-and-feel:

http://localhost:10000/?stylesheet=styles%2Fdark.css

The stylesheet URL is controlled by the @HtmlDoc(stylesheet) annotation.
The BasicRestServlet class defines the stylesheet served up as a static file:

@RestResource( htmldoc=@HtmlDoc( stylesheet="$C{REST/stylesheet,servlet:/styles/devops.css}", ), staticFiles={"styles:styles"} ) public abstract class BasicRestServlet extends RestServlet {...}

The "$C{REST/stylesheet,servlet:/styles/devops.css}" variable says to use the URI defined in your servlet's config file, if there is one, and to default to serving up the file org/apache/juneau/rest/styles/devops.css.

To provide your own stylesheet, simply override the stylesheet attribute and point to a different file:

@RestResource( htmldoc=@HtmlDoc( stylesheet="servlet:/my-styles/my-style.css}", ), staticFiles={"my-styles:my-styles"} ) public class MyResourceBaseClass extends BasicRestServlet {...}

You can try out different stylesheets by passing in a stylesheet attribute in the request URL.
The example above show this in use.

In case you're curious about how the menu item works, it's defined via a widget:

@RestResource( htmldoc=@HtmlDoc( widgets={ PoweredByApache.class, ContentTypeMenuItem.class, StyleMenuItem.class }, navlinks={ "options: ?method=OPTIONS", "$W{ContentTypeMenuItem}", "$W{StyleMenuItem}", "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java" }, ) public class RootResources extends BasicRestServletJenaGroup {...}

The StyleMenuItem is a widget that extends from MenuItemWidget, a specialized widget for creating pop-up menus.
In the case of StyleMenuItem, it's simply returning a list of links wrapped in a div tag:

import static org.apache.juneau.dto.html5.HtmlBuilder.*; public class StyleMenuItem extends MenuItemWidget { private static final String[] BUILT_IN_STYLES = {"devops", "light", "original", "dark"}; @Override /* Widget */ public String getLabel(RestRequest req) { return "styles"; } @Override /* MenuItemWidget */ public Div getContent(RestRequest req) throws Exception { Div div = div(); for (String s : BUILT_IN_STYLES) { java.net.URI uri = req.getUri(true, new AMap<String,String>().append("stylesheet", "styles/"+s+".css")); div.children(a(uri, s), br()); } return div; } }

7.29 - Default Headers

The following annotations are provided for specifying default header values for requests and responses:

Example:

// Servlet with default headers @RestResource( // Assume "text/json" Accept value when Accept not specified defaultRequestHeaders={"Accept: text/json"}, // Add a version header attribute to all responses defaultResponseHeaders={"X-Version: 1.0"} ) public MyRestServlet extends BasicRestServlet { ... }

Default headers can also be specified programmatically by overriding the following methods:

7.30 - Logging and Error Handling

The RestContext.REST_logger property allows you to configure logging for your resource.
The interface is shown below:

The logObjects() method is particularly useful because it allows you to pass in POJOs as arguments that serialized using SimpleJsonSerializer.DEFAULT_READABLE, but only if the message is actually logged.

Example:

logger.logObjects(DEBUG, "Pojo contents:\n{0}", myPojo);

By default, the Juneau framework uses the built-in Java Logging API for logging.
But you can define your own implementation to use any framework you wish.

The RestLogger instance is accessible via the following:

In addition, the logger can be accessed by passing it as a parameter to your REST java method:

@RestMethod() public Object doSomething(RestLogger logger) {...}

If your resource extends from RestServlet, you can also use and override the following methods:

7.31 - HTTP Status Codes

By default, a 200 (OK) status is automatically set as the HTTP status when a Java method executes successfully.

Other status codes can be generated by throwing a RestException with a specific HTTP status code, or calling HttpServletResponse.setStatus(int).

Non-OK (200) status codes are automatically triggered by the following conditions:

Code Description When triggered
401 Unauthorized A guard prevented the method from being executed
404 Not Found No matching path patterns were found on any method
405 Method Not Implemented A path pattern matched, but no Java methods were found for the HTTP method
406 Not Acceptable A path pattern matched, but no Java methods were found with a matching serializer for the Accept on the request
412 Precondition Failed A path pattern matched, but no Java methods were found that were not rejected by matchers
415 Unsupported Media Type A path pattern matched, but no Java methods were found with a matching parser for the Content-Type on the request
500 Internal Server Error The Java method threw an exception other than RestException

7.32 - Overloading HTTP Methods

Through the use of the built-in "method" GET parameter, you can implement requests beyond the basic REST http method types.

For example, the URL "/sample/foo?method=BAR" will cause the following method to be invoked...

@RestMethod(name="BAR") public void doBar(RestRequest req, RestResponse res) { // Handle BAR requests }

To support overloaded methods, the @RestResource(allowedMethodParams) setting must be enabled on your servlet.

@RestResource( // Allow &method parameter on BAR requests allowedMethodParams="BAR" )

7.33 - Built-in Parameters

The following URL parameters have special meaning and can be passed in through the URL of the request:

GET Parameter Description
&plainText=true Response will always be Content-Type: text/plain and the returned text will be human-readable (SERIALIZER_useWhitespace enabled).
Useful for debugging.
&debug=true Request body content will be dumped to log file.
&noTrace=true If an error occurs, don't log the stack trace to the log file.
Useful for automated JUnit testcases testing error states to prevent the log file from filling up with useless stack traces.
&method=X Overload the HTTP method as a GET parameter (e.g "POST").
Must be enabled via @RestResource(allowedMethodParams) setting.
&Header-Name=headerValue Specify a header value as a GET parameter.
Must be enabled via @RestResource(allowHeaderParams) setting.
&body=X Pass in the HTTP body content on PUT and POST methods as a UON-encoded GET parameter.
Must be enabled via @RestResource(allowBodyParam) setting.
&x-response-headers=X Pass-through headers to the response.
Must be a UON-encoded map of key-value pairs.

7.34 - Custom Serializers and Parsers

A very easy-to-use API is provided for defining your own serializers and parsers at both the servlet and method levels.

The following examples show a custom serializer and parser defined at the method level. It's the PhotosResource class pulled from the Samples project. It shows an example of defining a serializer and parser to handle images.

/** * Sample resource that allows images to be uploaded and retrieved. */ @RestResource( path="/photos", messages="nls/PhotosResource", title="Photo REST service", description="Use a tool like Poster to upload and retrieve jpeg and png images.", htmldoc=@HtmlDoc( navlinks={ "options: ?method=OPTIONS" } ) ) public class PhotosResource extends BasicRestServlet { // Our cache of photos private Map<Integer,Photo> photos = new TreeMap<Integer,Photo>(); /** Bean class for storing photos */ public static class Photo { private int id; BufferedImage image; Photo(int id, BufferedImage image) { this.id = id; this.image = image; } public URI getURI() throws URISyntaxException { return new URI("photos/"+id); } public int getID() { return id; } } /** GET request handler for list of all photos */ @RestMethod(name=GET, path="/") public Collection<Photo> getAllPhotos(RestRequest req, RestResponse res) throws Exception { res.setPageTitle("Photo REST service"); res.setPageText("Use a tool like Poster to upload and retrieve jpeg and png images."); return photos.values(); } /** GET request handler for single photo */ @RestMethod(name=GET, path="/{id}", serializers=ImageSerializer.class) public BufferedImage getPhoto(RestRequest req, @Path("id") int id) throws Exception { Photo p = photos.get(id); if (p == null) throw new RestException(SC_NOT_FOUND, "Photo not found"); return p.image; } /** PUT request handler */ @RestMethod(name=PUT, path="/{id}", parsers=ImageParser.class) public String addPhoto(RestRequest req, @Path("id") int id, @Body BufferedImage image) throws Exception { photos.put(id, new Photo(id, image)); return "OK"; } /** POST request handler */ @RestMethod(name=POST, path="/", parsers=ImageParser.class) public Photo setPhoto(RestRequest req, @Body BufferedImage image) throws Exception { int id = photos.size(); Photo p = new Photo(id, image); photos.put(id, p); return p; } /** DELETE request handler */ @RestMethod(name=DELETE, path="/{id}") public String deletePhoto(RestRequest req, @Path("id") int id) throws Exception { Photo p = photos.remove(id); if (p == null) throw new RestException(SC_NOT_FOUND, "Photo not found"); return "OK"; } /** OPTIONS request handler */ @RestMethod(name=OPTIONS, path="/*") public Swagger getOptions(RestRequest req) { return req.getSwagger(); } /** Serializer for converting images to byte streams */ @Produces("image/png,image/jpeg") public static class ImageSerializer extends OutputStreamSerializer { @Override /* Serializer */ public void serialize(Object o, OutputStream out, SerializerSession session) throws IOException, SerializeException { RenderedImage image = (RenderedImage)o; String mediaType = ctx.getMediaType(); ImageIO.write(image, mediaType.substring(mediaType.indexOf('/')+1), out); } } /** Parser for converting byte streams to images */ @Consumes("image/png,image/jpeg") public static class ImageParser extends InputStreamParser { @Override /* Parser */ public <T> T parse(InputStream in, ClassMeta<T> type, ParserSession session) throws ParseException, IOException { BufferedImage image = ImageIO.read(in); return (T)image; } } }

7.35 - Using with OSGi

Since REST servlets are basically just HttpServlets, incorporating them into an OSGi environment is pretty straightforward.

The following code shows how to register your REST servlets in an OSGi Activator:

package org.apache.juneau.examples.rest; import org.osgi.framework.*; import org.osgi.service.http.*; import org.osgi.util.tracker.*; import org.apache.juneau.rest.samples.*; /** * Activator class used when running samples as a bundle in an OSGi environment. */ public class Activator implements BundleActivator, ServiceTrackerCustomizer { private ServiceTracker httpServiceTracker; private BundleContext context; @Override /* BundleActivator */ public void start(BundleContext context) throws Exception { this.context = context; httpServiceTracker = new ServiceTracker(context, HttpService.class.getName(), this); httpServiceTracker.open(); } @Override /* BundleActivator */ public void stop(BundleContext context) throws Exception { httpServiceTracker.close(); } @Override /* ServiceTrackerCustomizer */ public Object addingService(ServiceReference reference) { Object service = context.getService(reference); if (service instanceof HttpService) { HttpService s = (HttpService)service; try { s.registerServlet("/sample", new MyRestServlet(), null, null); } catch (Exception e) { throw new RuntimeException(e); } } return service; } @Override /* ServiceTrackerCustomizer */ public void modifiedService(ServiceReference reference, Object service) { } @Override /* ServiceTrackerCustomizer */ public void removedService(ServiceReference reference, Object service) { } }

7.36 - Serverless Unit Testing

The MockRest class is a simple yet powerful interface for creating serverless unit tests for your REST interfaces.

The following shows a self-encapsulated standalone JUnit testcase that tests the functionality of a simple REST interface.

Example:

public class MockTest { // Our REST resource to test. @RestResource(serializers=JsonSerializer.Simple.class, parsers=JsonParser.class) public static class MyRest { @RestMethod(name=PUT, path="/String") public String echo(@Body String b) { return b; } } @Test public void testEcho() throws Exception { MockRest.create(MyRest.class).put("/String", "'foo'").execute().assertStatus(200).assertBody("'foo'")); } }

The API consists of the following classes:

The concept of the design is simple. The MockRest class is used to create instances of MockServletRequest and MockServletResponse which are passed directly to the call handler on the resource class RestCallHandler.service(HttpServletRequest,HttpServletResponse).

Breaking apart the fluent method call above will help you understand how this works.

@Test public void testEcho() throws Exception { // Instantiate our mock. MockRest mr = MockRest.create(MyRest.class); // Create a request. MockServletRequest req = mr.put("/String", "'foo'"); // Execute it (by calling RestCallHandler.service(...) and then returning the response object). MockServletResponse res = req.execute(); // Run assertion tests on the results. res.assertStatus(200); res.assertBody("'foo'"); }

The MockRest class provides the following methods for creating requests:

The MockServletRequest class provides default implementations for all the methods defined on the HttpServletRequest in addition to many convenience methods.

The following fluent convenience methods are provided for setting common Accept and Content-Type headers.

The following fluent convenience methods are provided for building up your request.

Fluent setters are provided for all common request headers:

The MockServletResponse class provides default implementations for all the methods defined on the HttpServletResponse in addition to many convenience methods.

The MockRest object can also be used with the RestClient class to perform serverless unit testing through the client API of REST resources.
This can be useful for testing of interface proxies against REST interfaces (described later).

The example above can be rewritten to use a mock as follows:

Example:

public class MockTest { // Our REST resource to test. @RestResource(serializers=JsonSerializer.Simple.class, parsers=JsonParser.class) public static class MyRest { @RestMethod(name=PUT, path="/String") public String echo(@Body String b) { return b; } } @Test public void testEcho() throws Exception { MockRest mr = MockRest.create(MyRest.class); RestClient rc = RestClient.create().mockHttpConnection(mr).build(); assertEquals("'OK'", rc.doPut("/String", "'OK'").getResponseAsString()); } }

The RestClientBuilder.mockHttpConnection(MockHttpConnection) method allows you to pass in a mocked interface for creating HTTP requests through the client interface.
The method creates a specialized HttpClientConnectionManager for handling requests by taking information on the client-side request and populating the MockServletRequest and MockServletResponse objects directly without involving any sockets.

7.37 - Using with Spring and Injection frameworks

The Juneau REST server API is compatible with dependency injection frameworks such as Spring.

The important class is the RestResourceResolver class which is used to resolve child servlet/resource implementation classes inside parent contexts. In other words, it's used for resolving @RestResource(children) instances.

The general approach starts with defining a resolver that uses the Spring application context for resolution:

public class SpringRestResourceResolver extends RestResourceResolverSimple { private final ApplicationContext appContext; public SpringRestResourceResolver(ApplicationContext appContext) { this.appContext = appContext; } @Override /* RestResourceResolverSimple */ public Object resolve(Class<?> resourceType, RestContextBuilder builder) throws Exception { Object resource = appContext.getBean(type); // If Spring can't resolve it, use default resolution (just look for no-arg constructor). if (resource == null) { resource = super.resolve(resourceType, builder); } return resource; } }

Next, define the Spring configuration to return our resolver:

@Configuration public abstract class MySpringConfiguration { @Autowired private static ApplicationContext appContext; public static ApplicationContext getAppContext(){ return appContext; } public static void setAppContext(ApplicationContext appContext){ MySpringConfiguration.appContext = appContext; } @Bean public RestResourceResolver restResourceResolver(ApplicationContext appContext) { return new SpringRestResourceResolver(appContext); } }

Finally, define your Root resource with a constructor that takes in our rest resource resolver and sets it on the config object during initialization.

@RestResource( children={ ... } ) public class Root extends BasicRestServletGroup { private final RestResourceResolver resolver; @Inject public Root(RestResourceResolver resolver) { this.resolver = resolver; } @RestHook(INIT) public void initSpring(RestContextBuilder builder) throws Exception { builder.setResourceResolver(resolver); } }

After that, just define constructors on your child resources to take in Spring beans:

@RestResource( path="/child" ) public class MyChildResource extends BasicRestServlet { private final Bean1 bean1; private final Bean2 bean2; private final Bean3 bean3; @Inject public MyChildResource(Bean1 bean1, Bean2 bean2, Bean3 bean3) { this.bean1 = bean1; this.bean2 = bean2; this.bean3 = bean3; }

7.38 - Using HTTP/2 features

Juneau is built as a veneer on top of the Servlet API, allowing you to use low-level Servlet APIs whenever needed.
This allows you to take advantage of the newest HTTP/2 features implemented in the new Servlet 4.0 specification.

7.39 - Other Notes

  • Subclasses can use either GenericServlet.init(ServletConfig) or GenericServlet.init() for initialization just like any other servlet.
  • The X-Response-Headers header can be used to pass through header values into the response. The value should be a URL-encoded map of key-value pairs. For example, to add a "Refresh: 1" header to the response to auto-refresh a page, the following parameter can be specified: "/sample?X-Response-Headers={Refresh=1}"

8 - juneau-rest-server-jaxrs

Maven Dependency

<dependency> <groupId>org.apache.juneau</groupId> <artifactId>juneau-rest-server-jaxrs</artifactId> <version>7.2.1</version> </dependency>

Java Library

juneau-rest-server-jaxrs-7.2.1.jar

OSGi Module

org.apache.juneau.rest.server_7.2.1.jar

The juneau-rest-server-jaxrs library provides an implementation of a MessageBodyReader and MessageBodyWriter to allow any of the Juneau serializers and parsers to be used in a JAX/RS environment.

8.1 - Juneau JAX-RS Provider

The Juneau framework contains the juneau-rest-server-jaxrs bundle for performing simple integration of Juneau serializers and parsers in JAX-RS compliant environments.

It should be noted that although some of the functionality of the Juneau Server API is provided through the JAX-RS integration components, it is not nearly as flexible as using the RestServlet class directly.

What you can do with the Juneau JAX-RS provider classes:

  • Use existing Juneau serializers and parsers for converting streams to POJOs and vis-versa.
  • Use annotations to specify filters and properties using the @RestMethod and JuneauProvider annotations.

What you can't do with the Juneau JAX-RS provider classes:

  • Specify or override serializers/parsers at the Java class and method levels.
    JAX-RS does not provide the capability to use different providers for the same media types at the class or method levels.
  • Specify or override filters and properties at the Java class level.
  • Default stylesheets for the HtmlDocSerializer class.
    It will produce HTML, but it won't contain any styles applied.
  • The ability to specify HTTP method, headers, and content using GET parameters.
    These make debugging REST interfaces using only a browser possible.
  • Class or method level encoding.
  • Class or method level guards.
  • Class or method level converters.

The Juneau JAX-RS provider API consists of the following classes:

  • BaseProvider - The base provider class that implements the JAX-RS MessageBodyReader and MessageBodyWriter interfaces.
  • JuneauProvider - Annotation that is applied to subclasses of BaseProvider to specify the serializers/parsers associated with a provider, and optionally filters and properties to apply to those serializers and parsers.
  • BasicProvider - A default provider that provides the same level of media type support as the BasicRestServlet class.

For the most part, when using these components, you'll either use the existing BasicProvider, or define your own by subclassing BaseProvider.

9 - juneau-rest-client

Maven Dependency

<dependency> <groupId>org.apache.juneau</groupId> <artifactId>juneau-rest-client</artifactId> <version>7.2.1</version> </dependency>

Java Library

juneau-rest-client-7.2.1.jar

OSGi Module

org.apache.juneau.rest.client_7.2.1.jar

The REST client API provides the ability to access remote REST interfaces and transparently convert the input and output to and from POJOs using any of the provided serializers and parsers.

Built upon the Apache HttpClient libraries, it extends that API and provides specialized APIs for working with REST interfaces while maintaining all the functionality available in the HttpClient API.

// Create a reusable JSON client. try (RestClient client = RestClient.create().json().build()) { // The address of the root resource. String url = "http://localhost:10000/addressBook"; // Do a REST GET against a remote REST interface and convert // the response to an unstructured ObjectMap object. ObjectMap m1 = client.doGet(url).getResponse(ObjectMap.class); // Same as above, except parse the JSON as a bean. AddressBook a2 = client.doGet(url).getResponse(AddressBook.class); } try (RestClient client = RestClient.create().serializer(XmlSerializer.class).parser(XmlSerializer.class).build()) { // Add a person to the address book. // Use XML as the transport medium. Person p = new Person("Joe Smith", 21); int returnCode = client.doPost(url + "/entries", p).run(); }

Juneau provides an HTTP client API that makes it extremely simple to connect to remote REST interfaces and seemlessly send and receive serialized POJOs in requests and responses.

Features
  • Converts POJOs directly to HTTP request message bodies using Serializer classes.
  • Converts HTTP response message bodies directly to POJOs using Parser classes.
  • Serializes and parses HTTP request and response parts (query/form-data parameters, headers, path variables) using OpenAPI marshalling and validation.
  • Exposes the full functionality of the Apache HttpClient API by exposing all methods defined on the HttpClientBuilder class.

The client API is designed to work as a thin layer on top of the proven Apache HttpClient API. By leveraging the HttpClient library, details such as SSL certificate negotiation, proxies, encoding, etc... are all handled in Apache code.

The Juneau client API prereq's Apache HttpClient 4.5+. At a minimum, the following jars are required:

  • httpclient-4.5.jar
  • httpcore-4.4.1.jar
  • httpmime-4.5.jar
Example:

// Examples below use the Juneau Address Book resource example // Create a reusable client with JSON support try (RestClient client = RestClient.create().json().build()) { // GET request, ignoring output try { int rc = client.doGet("http://localhost:10000/addressBook").run(); // Succeeded! } catch (RestCallException e) { // Failed! System.err.println( String.format("status=%s, message=%s", e.getResponseStatus(), e.getResponseMessage()) ); } // Remaining examples ignore thrown exceptions. // GET request, secure, ignoring output client.doGet("https://localhost:9443/sample/addressBook").run(); // GET request, getting output as a String. No POJO parsing is performed. // Note that when calling one of the getX() methods, you don't need to call connect() or disconnect(), since // it's automatically called for you. String output = client.doGet("http://localhost:10000/addressBook") .getResponseAsString(); // GET request, getting output as a Reader Reader r = client.doGet("http://localhost:10000/addressBook") .getReader(); // GET request, getting output as an untyped map // Input must be an object (e.g. "{...}") ObjectMap m = client.doGet("http://localhost:10000/addressBook/0") .getResponse(ObjectMap.class); // GET request, getting output as an untyped list // Input must be an array (e.g. "[...]") ObjectList l = client.doGet("http://localhost:10000/addressBook") .getResponse(ObjectList.class); // GET request, getting output as a parsed bean // Input must be an object (e.g. "{...}") // Note that you don't have to do any casting! Person p = client.doGet("http://localhost:10000/addressBook/0") .getResponse(Person.class); // GET request, getting output as a parsed bean // Input must be an array of objects (e.g. "[{...},{...}]") Person[] pa = client.doGet("http://localhost:10000/addressBook") .getResponse(Person[].class); // Same as above, except as a List<Person> List<Person> pl = client.doGet("http://localhost:10000/addressBook") .getResponse(List.class, Person.class); // GET request, getting output as a parsed string // Input must be a string (e.g. "<string>foo</string>" or "'foo'") String name = client.doGet("http://localhost:10000/addressBook/0/name") .getResponse(String.class); // GET request, getting output as a parsed number // Input must be a number (e.g. "<number>123</number>" or "123") int age = client.doGet("http://localhost:10000/addressBook/0/age") .getResponse(Integer.class); // GET request, getting output as a parsed boolean // Input must be a boolean (e.g. "<boolean>true</boolean>" or "true") boolean isCurrent = client.doGet("http://localhost:10000/addressBook/0/addresses/0/isCurrent") .getResponse(Boolean.class); } // GET request, getting a filtered object try (RestClient client = RestClient.create().pojoSwaps(CalendarSwap.ISO8601.class).build()) { Calendar birthDate = client.doGet("http://localhost:10000/addressBook/0/birthDate") .getResponse(GregorianCalendar.class); // PUT request on regular field String newName = "John Smith"; int rc = client.doPut("http://localhost:10000/addressBook/0/name", newName).run(); // PUT request on filtered field Calendar newBirthDate = new GregorianCalendar(1, 2, 3, 4, 5, 6); rc = client.doPut("http://localhost:10000/addressBook/0/birthDate", newBirthDate).run(); // POST of a new entry to a list Address newAddress = new Address("101 Main St", "Anywhere", "NY", 12121, false); rc = client.doPost("http://localhost:10000/addressBook/0/addresses", newAddress).run(); }

Notes:
  • The RestClient class exposes all the builder methods on the Apache HttpClient HttpClientBuilder class.
    Use these methods to provide any customized HTTP client behavior.

9.1 - REST Proxies

The juneau-rest-client library 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.

Remote resources are instantiated using one of the following methods:

Annotations are used on the interface and interface methods to specify how to convert input and output to HTTP headers, query parameters, form post parameters, or request/response bodies.

Example:

@RemoteResource(path="/petstore") public interface PetStore { @RemoteMethod(httpMethod=POST, path="/pets") String addPet( @Body CreatePet pet, @Header("E-Tag") UUID etag, @Query("debug") boolean debug ); }

// Use a RestClient with default Simple JSON support. try (RestClient client = RestClient.create().simpleJson().build()) { PetStore store = client.getRemoteResource(PetStore.class, "http://localhost:10000"); CreatePet pet = new CreatePet("Fluffy", 9.99); String response = store.createPet(pet, UUID.randomUUID(), true); }

The call above translates to the following REST call:

POST http://localhost:10000/petstore/pets?debug=true HTTP/1.1 Accept: application/json Content-Type: application/json E-Tag: 475588d4-0b27-4f56-9296-cc683251d314 { name: 'Fluffy', price: 9.99 }

9.1.1 - @RemoteResource

The @RemoteResource annotation is used on your interface class to identify it as a REST proxy interface.

The @RemoteResource annotation is optional, but often included for code readability.

@RemoteResource(path)

The @RemoteResource(path) annotation is used to define the HTTP path of the REST service.

The path can be an absolute path to your REST service.

Example:

@RemoteResource(path="http://localhost:10000/petstore") public interface PetStore {...}

PetStore p = client.getRemoteResource(PetStore.class);

When a relative path is specified, it's relative to the root-url defined on the RestClient used to instantiate the interface.

Example:

@RemoteResource(path="/petstore") public interface PetStore {...}

RestClient client = RestClient.create().json().rootUrl("http://localhost:10000").build(); PetStore p = client.getRemoteResource(PetStore.class);

When no path is specified, the root-url defined on the RestClient is used.

Example:

@RemoteResource public interface PetStore {...}

RestClient client = RestClient.create().json().rootUrl("http://localhost:10000/petstore").build(); PetStore p = client.getRemoteResource(PetStore.class);

9.1.2 - @RemoteMethod

The @RemoteMethod annotation is applied to methods of @RemoteResource-annotated interfaces to identify REST endpoints.

@RemoteMethod(method/path)

The HTTP method and path are mapped to a Java method using the method and path annotations.

Example:

@RemoteResource public interface PetStore { // GET /pets/{petId} @RemoteMethod(method="GET", path="/pets/{petId}") Pet getPet(@Path("petId") int id); }

The Java method name can be anything.

Inferred method/path

In such cases, method and path annotations are optional if you follow certain naming conventions on your method that identify the method and path.

For example, the getPet method below defaults to GET /pet:

@RemoteResource public interface PetStore { // GET /pet @RemoteMethod Pet getPet(...); }

In such cases, the @RemoteMethod annotation is optional.

Method names matching the following pattern are assumed to be implying the HTTP method name:

(get|put|post|delete|options|head|connect|trace|patch).*

do(?i)(get|put|post|delete|options|head|connect|trace|patch)

Examples:
Java method name Inferred HTTP method Inferred HTTP path
getPet() GET /pet
get() GET /
postPet() POST /pet
fooPet() [default] /fooPet
doGet() GET /
doGET() GET /
doFoo() [default] /doFoo
@RemoteMethod(returns)

The return type of the Java methods of can be any of the following:

  • void - Don't parse any response.
    Note that the method will still throw a runtime exception if an error HTTP status is returned.
  • Any parsable POJO - The body of the response will be converted to the POJO using the parser defined on the RestClient based on the Content-Type of the response.
  • Any @Response-annotated type. (described later)
  • HttpResponse - Returns the raw HttpResponse returned by the inner HttpClient.
  • Reader - Returns access to the raw reader of the response.
  • InputStream - Returns access to the raw input stream of the response.

If you're only interested in the HTTP status code of the response, you can use the returns annotation with a value of STATUS:

Example:

@RemoteResource public interface PetStore { // POST /pets // Returns HTTP status code. @RemoteMethod(returns=STATUS) int postPets(...); }

If your RestClient does not have a parser associated with it, then the value is converted directly from a String using the rules defined in POJOs Convertible to/from Strings.

9.1.3 - @Body

The @Body annotation can be applied to arguments of @RemoteMethod-annotated methods to denote that they are the HTTP body of the request.

Examples:

// Used on parameter @RemoteResource(path="/petstore") public interface PetStore { @RemoteMethod(path="/pets") String addPet(@Body Pet pet); }

// Used on class @RemoteResource(path="/petstore") public interface PetStore { @RemoteMethod(path="/pets") String addPet(Pet pet); } @Body public class Pet {...}

The argument can be any of the following types:

  • Any serializable POJO - Converted to output using the Serializer registered with the RestClient.
    Content-Type is set to that of the Serializer.
  • Reader - Raw contents of Reader will be serialized to remote resource.
    Content-Type is set to "text/plain".
  • InputStream - Raw contents of InputStream will be serialized to remote resource.
    Content-Type is set to "application/octet-stream".
  • NameValuePairs - Converted to a URL-encoded FORM post.
    Content-Type is set to "aplication/x-www-form-urlencoded".
  • HttpEntity - Bypass Juneau serialization and pass HttpEntity directly to HttpClient.

OpenAPI schema based serialization can be used by using the OpenApiSerializer class.

@RemoteMethod(path="/comma-delimited-pipe-delimited-ints") String addCommaDelimitedPipeDelimitedInts( @Body( serializer=OpenApiSerializer.class, schema=@Schema( type="array", collectionFormat="pipes", items=@Items( type="array" items=@SubItems( type="int32", // Auto-validates on client side! minimum="0", maximum="64" ) ) ) ) int[][] input );

See Overview > juneau-marshall > OpenAPI Details > OpenAPI Serializers for information about supported data types in OpenAPI serialization.

If your RestClient class does not have a serializer associated with it, the body will automatically be serialized to a string using the rules defined in POJOs Convertible to/from Strings.

9.1.4 - @FormData

The @FormData annotation can be applied to arguments of @RemoteMethod-annotated methods to denote that they are form-data parameters on the request.

  • FormData
    • _default - Default value if not present.
    • _enum - Input validation. Must match one of the values.
    • allowEmptyValue - Input validation. Allow empty value.
    • collectionFormat - How collections of items are formatted.
    • exclusiveMaximum - Input validation. Whether maximum is exclusive.
    • exclusiveMinimum - Input validation. Whether minimum is exclusive.
    • format - The schema type format.
    • items - The schema of items in a collection.
    • maximum - Input validation. Maximum numeric value.
    • maxItems - Input validation. Maximum number of items in a collection.
    • maxLength - Input validation. Maximum length of a string.
    • minimum - Input validation. Minimum numeric value.
    • minItems - Input validation. Minimum number of items in a collection.
    • minLength - Input validation. Minimum length of a string.
    • multipleOf - Input validation. Number must be a multiple of.
    • name - Form data entry name.
    • pattern- Input validation. Must match regular expression.
    • required- Input validation. Form data entry must be present.
    • serializer- Override the part serializer.
    • skipIfEmpty- Don't add if value is null or empty.
    • type - The schema type.
    • uniqueItems - Input validation. Collections must contain unique items only.
Example:

@RemoteResource(path="/myproxy") public interface MyProxy { // Explicit names specified for form data parameters. @RemoteMethod String postParameters( @FormData("foo") String foo, @FormData("bar") MyPojo pojo ); // Multiple values pulled from a NameValuePairs object. // Name "*" is inferred. @RemoteMethod String postNameValuePairs(@FormData NameValuePairs nameValuePairs); // Multiple values pulled from a Map. @RemoteMethod String postMap(@FormData Map<String,Object> map); // Multiple values pulled from a bean. @RemoteMethod String postBean(@FormData MyBean bean); // An entire form-data HTTP body as a String. @RemoteMethod String postString(@FormData String string); // An entire form-data HTTP body as a Reader. @RemoteMethod String postReader(@FormData Reader reader); }

Single-part arguments (i.e. those with name != "*") can be any of the following types:

Multi-part arguments (i.e. those with name == "*" or empty) can be any of the following types:

  • Reader - Raw contents of Reader will be serialized to remote resource.
  • InputStream - Raw contents of InputStream will be serialized to remote resource.
  • NameValuePairs - Converted to a URL-encoded FORM post.
  • Map - Converted to key-value pairs.
    Values serialized using the registered HttpPartSerializer (OpenApiSerializer by default).
  • Bean - Converted to key-value pairs.
    Values serialized using the registered HttpPartSerializer (OpenApiSerializer by default).
  • CharSequence - Used directly as am "application/x-www-form-urlencoded" entity.

See the link below for information about supported data types in OpenAPI serialization.

See Also:

9.1.5 - @Query

The @Query annotation can be applied to arguments of @RemoteMethod-annotated methods to denote that they are query parameters on the request.

  • Query
    • _default - Default value if not present.
    • _enum - Input validation. Must match one of the values.
    • allowEmptyValue - Input validation. Allow empty value.
    • collectionFormat - How collections of items are formatted.
    • exclusiveMaximum - Input validation. Whether maximum is exclusive.
    • exclusiveMinimum - Input validation. Whether minimum is exclusive.
    • format - The schema type format.
    • items - The schema of items in a collection.
    • maximum - Input validation. Maximum numeric value.
    • maxItems - Input validation. Maximum number of items in a collection.
    • maxLength - Input validation. Maximum length of a string.
    • minimum - Input validation. Minimum numeric value.
    • minItems - Input validation. Minimum number of items in a collection.
    • minLength - Input validation. Minimum length of a string.
    • multipleOf - Input validation. Number must be a multiple of.
    • name - Query parameter name.
    • pattern - Input validation. Must match regular expression.
    • required - Input validation. Query parameter must be present.
    • serializer - Override the part serializer.
    • skipIfEmpty- Don't add if value is null or empty.
    • type - The schema type.
    • uniqueItems - Input validation. Collections must contain unique items only.
Example:

@RemoteResource(path="/myproxy") public interface MyProxy { // Explicit names specified for query parameters. @RemoteMethod String parameters( @Query("foo") String foo, @Query("bar") MyPojo pojo); // Multiple values pulled from a NameValuePairs object. // Same as @Query("*"). @RemoteMethod String nameValuePairs(@Query NameValuePairs nameValuePairs); // Multiple values pulled from a Map. // Same as @Query("*"). @RemoteMethod String map(@Query Map<String,Object> map); // Multiple values pulled from a bean. // Same as @Query("*"). @RemoteMethod String bean(@Query MyBean myBean); // An entire query string as a String. // Same as @Query("*"). @RemoteMethod String string(@Query String string); // An entire query string as a Reader. // Same as @Query("*"). @RemoteMethod String reader(@Query Reader reader); }

Single-part arguments (i.e. those with name != "*") can be any of the following types:

Multi-part arguments (i.e. those with name == "*" or empty) can be any of the following types:

  • Reader - Raw contents of Reader will be serialized directly a query string.
  • NameValuePairs - Serialized as individual query parameters.
  • Map - Converted to key-value pairs.
    Values serialized using the registered HttpPartSerializer (OpenApiSerializer by default).
  • Bean - Converted to key-value pairs.
    Values serialized using the registered HttpPartSerializer (OpenApiSerializer by default).
  • CharSequence - Serialized directly a query string.

See the link below for information about supported data types in OpenAPI serialization.

See Also:

9.1.6 - @Header

The @Header annotation can be applied to arguments of @RemoteMethod-annotated methods to denote that they are header parameters on the request.

  • Header
    • _default - Default value if not present.
    • _enum - Input validation. Must match one of the values.
    • allowEmptyValue - Input validation. Allow empty value.
    • collectionFormat - How collections of items are formatted.
    • exclusiveMaximum - Input validation. Whether maximum is exclusive.
    • exclusiveMinimum - Input validation. Whether minimum is exclusive.
    • format - The schema type format.
    • items - The schema of items in a collection.
    • maximum - Input validation. Maximum numeric value.
    • maxItems - Input validation. Maximum number of items in a collection.
    • maxLength - Input validation. Maximum length of a string.
    • minimum - Input validation. Minimum numeric value.
    • minItems - Input validation. Minimum number of items in a collection.
    • minLength - Input validation. Minimum length of a string.
    • multipleOf - Input validation. Number must be a multiple of.
    • name - Header name.
    • pattern - Input validation. Must match regular expression.
    • required - Input validation. Header must be present.
    • serializer - Override the part serializer.
    • skipIfEmpty - Don't add if value is null or empty.
    • type - The schema type.
    • uniqueItems - Input validation. Collections must contain unique items only.
Example:

@RemoteResource(path="/myproxy") public interface MyProxy { // Explicit names specified for HTTP headers. // pojo will be converted to UON notation (unless plain-text parts enabled). @RemoteMethod(path="/mymethod1") String myProxyMethod1(@Header("Foo") String foo, @Header("Bar") MyPojo pojo); // Multiple values pulled from a NameValuePairs object. // Same as @Header("*"). @RemoteMethod(path="/mymethod2") String myProxyMethod2(@Header NameValuePairs nameValuePairs); // Multiple values pulled from a Map. // Same as @Header("*"). @RemoteMethod(path="/mymethod3") String myProxyMethod3(@Header Map<String,Object> map); // Multiple values pulled from a bean. // Same as @Header("*"). @RemoteMethod(path="/mymethod4") String myProxyMethod4(@Header MyBean myBean); }

Single-part arguments (i.e. those with name != "*") can be any of the following types:

Multi-part arguments (i.e. those with name == "*" or empty) can be any of the following types:

See the link below for information about supported data types in OpenAPI serialization.

See Also:

9.1.7 - @Path

The @Path annotation can be applied to arguments of @RemoteMethod-annotated methods to denote that they are path parameters on the request.

  • Path
    • _enum - Input validation. Must match one of the values.
    • allowEmptyValue - Input validation. Allow empty value.
    • collectionFormat - How collections of items are formatted.
    • exclusiveMaximum - Input validation. Whether maximum is exclusive.
    • exclusiveMinimum - Input validation. Whether minimum is exclusive.
    • format - The schema type format.
    • items - The schema of items in a collection.
    • maximum - Input validation. Maximum numeric value.
    • maxLength - Input validation. Maximum length of a string.
    • minimum - Input validation. Minimum numeric value.
    • minLength - Input validation. Minimum length of a string.
    • multipleOf - Input validation. Number must be a multiple of.
    • name - Path variable name.
    • pattern - Input validation. Must match regular expression.
    • serializer - Override the part serializer.
    • type - The schema type.
Example:

@RemoteResource(path="/myproxy") public interface MyProxy { // Explicit names specified for path parameters. // pojo will be converted to UON notation (unless plain-text parts enabled). @RemoteMethod(path="/mymethod1/{foo}/{bar}") String myProxyMethod1(@Path("foo") String foo, @Path("bar") MyPojo pojo); // Multiple values pulled from a NameValuePairs object. // Same as @Path("*"). @RemoteMethod(path="/mymethod2/{foo}/{bar}/{baz}") String myProxyMethod2(@Path NameValuePairs nameValuePairs); // Multiple values pulled from a Map. // Same as @Path("*"). @RemoteMethod(path="/mymethod3/{foo}/{bar}/{baz}") String myProxyMethod3(@Path Map<String,Object> map); // Multiple values pulled from a bean. // Same as @Path("*"). @RemoteMethod(path="/mymethod4/{foo}/{bar}/{baz}") String myProxyMethod4(@Path MyBean myBean); }

Single-part arguments (i.e. those with name != "*") can be any of the following types:

Multi-part arguments (i.e. those with name == "*" or empty) can be any of the following types:

See the link below for information about supported data types in OpenAPI serialization.

See Also:

9.1.8 - @Request

The @Request annotation can be applied to a type of a @RemoteMethod-annotated method to identify it as a bean for setting HTTP parts through a bean-like interface.

Example:

@RemoteResource(path="/petstore") public interface PetStore { @RemoteMethod String postPet(CreatePetRequest bean); }

@Request public class CreatePetRequest { private CreatePet pet; public CreatePetRequest(String name, float price) { this.pet = new CreatePet(name, price); } @Body public CreatePet getBody() { return this.pet; } @Query public Map<String,Object> getQueryParams() { return new ObjectMap().append("debug", true); } @Header("E-Tag") public static UUID getUUID() { return UUID.generatedUUID(); } }

PetStore store = restClient.getRemoteResource(PetStore.class, "http://localhost:10000"); CreatePetRequest requestBean = new CreatePetRequest("Fluffy", 9.99); String response = store.postPet(requestBean);

The @Request annotation can be applied to either the class or argument.

The annotated methods must be no-arg and public. They can be named anything.

Any of the following annotations can be used on the methods:

The behavior and functionality of all of the annotations are the same as if they were used on method arguments directly. This means full support for OpenAPI serialization and validation.

Annotations on methods are inherited from parent classes and interfaces.
For example, the request bean above could have defined annotations in an interface to keep them clear from the implementation:

@Request public interface CreatePetRequest { @Body CreatePet getBody(); @Query Map<String,Object> getQueryParams(); @Header("E-Tag") UUID getUUID(); }

public class CreatePetRequestImpl implements CreatePetRequest { public CreatePetRequestImpl(String name, float price) {...} @Override public CreatePet getBody() { return this.pet; } @Override public Map<String,Object> getQueryParams() { return new ObjectMap().append("debug", true); } @Override public UUID getUUID() { return UUID.generateUUID(); } }

9.1.9 - @Response

The @Response annotation can be applied to types returned by @RemoteMethod-annotated methods.

The @Response annotation can be used to define interfaces for retrieving response parts using a bean-like proxy.

Example:

@RemoteResource public interface PetStore { @RemoteMethod CreatePetResponse postPet(...); }

@Response public interface CreatePetResponse { @ResponseBody Pet getBody(); @ResponseHeader("E-Tag") UUID getUUID(); @ResponseStatus int getStatus(); }

PetStore store = restClient.getRemoteResource(PetStore.class, "http://localhost:10000"); CreatePetResponse response = store.postPet(...); Pet pet = response.getBody(); UUID uuid = response.getUUID(); int status = response.getStatus();

The annotated methods must be no-arg. They can be named anything.

Any of the following annotations can be used on the methods:

The behavior and functionality of all of the annotations are the same as if they were used on method arguments directly. This means full support for OpenAPI serialization and validation.

9.1.10 - Dual-purpose (end-to-end) interfaces

A common coding practice is to use the same Java interface to define both your server and client side REST interfaces. The advantage to this approach is that changes that you make to your REST interface can be reflected in both places at the same time, reducing the chances for compatibility mistakes.

What makes this possible is that method-level annotations such as @RestMethod and parameter-level annotations such as @Query are inherited from parent classes. This normally isn't possible, but the framework will spider up the parent hierarchy of classes to find method and parameter level annotations defined on overridden methods.

The general approach is to define your @RemoteResource-annotated interface first. The following example is pulled from the PetStore app:

@RemoteResource(path="/petstore") public interface PetStore { @RemoteMethod(method=GET, path="/pet") public Collection<Pet> getPets() throws NotAcceptable; @RemoteMethod(method=DELETE, path="/pet/{petId}") public Ok deletePet( @Header( name="api_key", description="Security API key", required=true, example="foobar" ) String apiKey, @Path( name="petId", description="Pet id to delete", example="123" ) long petId ) throws IdNotFound, NotAcceptable; ...

Next you define the implementation of your interface as a normal Juneau REST resource:

@RestResource( path="/petstore", title="Petstore application", ... ) public class PetStoreResource extends BasicRestServletJena implements PetStore { ... @Override /* PetStore */ @RestMethod( name=GET, path="/pet", summary="All pets in the store", ... ) public Collection<Pet> getPets() throws NotAcceptable { return store.getPets(); } @Override /* PetStore */ @RestMethod( name=DELETE, path="/pet/{petId}", summary="Deletes a pet", ... ) public Ok deletePet(String apiKey, long petId) throws IdNotFound, NotAcceptable { store.removePet(petId); return OK; }

Then use the interface as a remote resource like so:

try (RestClient rc = RestClient.create().json().rootUrl("http://localhost:10000").build()) { PetStore ps = rc.getRemoteResource(PetStore.class); for (Pet x : ps.getPets()) { ps.deletePet("my-special-key", x.getId()); System.err.println("Deleted pet: id=" + x.getId()); } }

In the example above, we chose to add the @RestMethod annotation to the implementation class. However, they could have been added to the interface instead.

Note how we didn't need to use the @Header and @Path annotations in our implementation since the annotations were inherited from the interface.

9.2 - SSL Support

The simplest way to enable SSL support in the client is to use the RestClientBuilder.enableLaxSSL() method.

Example:

// Create a client that ignores self-signed or otherwise invalid certificates. RestClient rc = RestClient.create().enableLaxSSL().build();

A more typical scenario using default cert and hostname verification is shown here:

RestClient rc = RestClient.create().enableSSL().sslProtocols("TLSv1.2").build();

The following convenience methods are provided in the builder class for specifying SSL parameters:

SSL support can also be enabled by passing in your own connection manager using RestClientBuilder.httpClientConnectionManager(HttpClientConnectionManager).

9.3 - Authentication

The Juneau REST client itself does not implement any support for authentication. Instead, it delegates it to the underlying Apache HTTP Client interface.

The following sections show how some common authentication mechanisms can be set up using HTTP Client APIs.

9.3.1 - BASIC Authentication

The RestClientBuilder.basicAuth(String,int,String,String) method can be used to quickly enable BASIC authentication support.

Example:

// Create a client that performs BASIC authentication using the specified user/pw. RestClient restClient = RestClient.create() .basicAuth(HOST, PORT, USER, PW) .build();

This is functionally equivalent to the following:

RestClientBuilder builder = RestClient.create(); AuthScope scope = new AuthScope(HOST, PORT); Credentials up = new UsernamePasswordCredentials(USER, PW); CredentialsProvider p = new BasicCredentialsProvider(); p.setCredentials(scope, up); builder.setDefaultCredentialsProvider(p);

9.3.2 - FORM-based Authentication

The RestClientBuilder class does not itself provide FORM-based authentication since there is no standard way of providing such support.
Typically, to perform FORM-based or other types of authentication, you'll want to create your own subclass of RestClientBuilder and override the RestClientBuilder.createHttpClient() method to provide an authenticated client.

The following example shows how the JazzRestClient class provides FORM-based authentication support.

/** * Constructor. */ public JazzRestClientBuilder(URI jazzUri, String user, String pw) throws IOException { ... } /** * Override the createHttpClient() method to return an authenticated client. */ @Override /* RestClientBuilder */ protected CloseableHttpClient createHttpClient() throws Exception { CloseableHttpClient client = super.createHttpClient(); formBasedAuthenticate(client); visitAuthenticatedURL(client); return client; } /* * Performs form-based authentication against the Jazz server. */ private void formBasedAuthenticate(HttpClient client) throws IOException { URI uri2 = jazzUri.resolve("j_security_check"); HttpPost request = new HttpPost(uri2); request.setConfig(RequestConfig.custom().setRedirectsEnabled(false).build()); // Charset must explicitly be set to UTF-8 to handle user/pw with non-ascii characters. request.addHeader("Content-Type", "application/x-www-form-urlencoded; charset=utf-8"); NameValuePairs params = new NameValuePairs() .append(new BasicNameValuePair("j_username"", user)) .append(new BasicNameValuePair("j_password", pw)); request.setEntity(new UrlEncodedFormEntity(params)); HttpResponse response = client.execute(request); try { int rc = response.getStatusLine().getStatusCode(); Header authMsg = response.getFirstHeader("X-com-ibm-team-repository-web-auth-msg"); if (authMsg != null) throw new IOException(authMsg.getValue()); // The form auth request should always respond with a 200 ok or 302 redirect code if (rc == SC_MOVED_TEMPORARILY) { if (response.getFirstHeader("Location").getValue().matches("^.*/auth/authfailed.*$")) throw new IOException("Invalid credentials."); } else if (rc != SC_OK) { throw new IOException("Unexpected HTTP status: " + rc); } } finally { EntityUtils.consume(response.getEntity()); } } /* * This is needed for Tomcat because it responds with SC_BAD_REQUEST when the j_security_check URL is visited before an * authenticated URL has been visited. This same URL must also be visited after authenticating with j_security_check * otherwise tomcat will not consider the session authenticated */ private int visitAuthenticatedURL(HttpClient httpClient) throws IOException { HttpGet authenticatedURL = new HttpGet(jazzUri.resolve("authenticated/identity")); HttpResponse response = httpClient.execute(authenticatedURL); try { return response.getStatusLine().getStatusCode(); } finally { EntityUtils.consume(response.getEntity()); } }

9.3.3 - OIDC Authentication

The following example shows how the JazzRestClient class provides OIDC authentication support.

/** * Constructor. */ public JazzRestClientBuilder(URI jazzUri, String user, String pw) throws IOException { ... } /** * Override the createHttpClient() method to return an authenticated client. */ @Override /* RestClientBuilder */ protected CloseableHttpClient createHttpClient() throws Exception { CloseableHttpClient client = super.createHttpClient(); oidcAuthenticate(client); return client; } private void oidcAuthenticate(HttpClient client) throws IOException { HttpGet request = new HttpGet(jazzUri); request.setConfig(RequestConfig.custom().setRedirectsEnabled(false).build()); // Charset must explicitly be set to UTF-8 to handle user/pw with non-ascii characters. request.addHeader("Content-Type", "application/x-www-form-urlencoded; charset=utf-8"); HttpResponse response = client.execute(request); try { int code = response.getStatusLine().getStatusCode(); // Already authenticated if (code == SC_OK) return; if (code != SC_UNAUTHORIZED) throw new RestCallException("Unexpected response during OIDC authentication: " + response.getStatusLine()); // x-jsa-authorization-redirect String redirectUri = getHeader(response, "X-JSA-AUTHORIZATION-REDIRECT"); if (redirectUri == null) throw new RestCallException("Expected a redirect URI during OIDC authentication: " + response.getStatusLine()); // Handle Bearer Challenge HttpGet method = new HttpGet(redirectUri + "&prompt=none"); addDefaultOidcHeaders(method); response = client.execute(method); code = response.getStatusLine().getStatusCode(); if (code != SC_OK) throw new RestCallException("Unexpected response during OIDC authentication phase 2: " + response.getStatusLine()); String loginRequired = getHeader(response, "X-JSA-LOGIN-REQUIRED"); if (! "true".equals(loginRequired)) throw new RestCallException("X-JSA-LOGIN-REQUIRED header not found on response during OIDC authentication phase 2: " + response.getStatusLine()); method = new HttpGet(redirectUri + "&prompt=none"); addDefaultOidcHeaders(method); response = client.execute(method); code = response.getStatusLine().getStatusCode(); if (code != SC_OK) throw new RestCallException("Unexpected response during OIDC authentication phase 3: " + response.getStatusLine()); // Handle JAS Challenge method = new HttpGet(redirectUri); addDefaultOidcHeaders(method); response = client.execute(method); code = response.getStatusLine().getStatusCode(); if (code != SC_OK) throw new RestCallException("Unexpected response during OIDC authentication phase 4: " + response.getStatusLine()); cookie = getHeader(response, "Set-Cookie"); Header[] defaultHeaders = new Header[] { new BasicHeader("User-Agent", "Jazz Native Client"), new BasicHeader("X-com-ibm-team-configuration-versions", "com.ibm.team.rtc=6.0.0,com.ibm.team.jazz.foundation=6.0"), new BasicHeader("Accept", "text/json"), new BasicHeader("Authorization", "Basic " + StringUtils.base64EncodeToString(user + ":" + pw)), new BasicHeader("Cookie", cookie) }; setDefaultHeaders(Arrays.asList(defaultHeaders)); } finally { EntityUtils.consume(response.getEntity()); } } private void addDefaultOidcHeaders(HttpRequestBase method) { method.addHeader("User-Agent", "Jazz Native Client"); method.addHeader("X-com-ibm-team-configuration-versions", "com.ibm.team.rtc=6.0.0,com.ibm.team.jazz.foundation=6.0"); method.addHeader("Accept", "text/json"); if (cookie != null) { method.addHeader("Authorization", "Basic " + StringUtils.base64EncodeToString(user + ":" + pw)); method.addHeader("Cookie", cookie); } }

9.4 - Using Response Patterns

One issue with REST (and HTTP in general) is that the HTTP response code must be set as a header before the body of the request is sent.
This can be problematic when REST calls invoke long-running processes, pipes the results through the connection, and then fails after an HTTP 200 has already been sent.

One common solution is to serialize some text at the end to indicate whether the long-running process succeeded (e.g. "FAILED" or "SUCCEEDED").

The RestClient class has convenience methods for scanning the response without interfering with the other methods used for retrieving output.

The following example shows how the RestCall.successPattern(String) method can be used to look for a SUCCESS message in the output:

Example:

// Throw a RestCallException if SUCCESS is not found in the output. restClient.doPost(URL) .successPattern("SUCCESS") .run();

The RestCall.failurePattern(String) method does the opposite. It throws an exception if a failure message is detected.

Example:

// Throw a RestCallException if FAILURE or ERROR is found in the output. restClient.doPost(URL) .failurePattern("FAILURE|ERROR") .run();

These convenience methods are specialized methods that use the RestCall.responsePattern(ResponsePattern) method which uses regular expression matching against the response body.
This method can be used to search for arbitrary patterns in the response body.

The following example shows how to use a response pattern finder to find and capture patterns for "x=number" and "y=string" from a response body.

Example:

final List<Number> xList = new ArrayList<Number>(); final List<String> yList = new ArrayList<String>(); String responseText = restClient.doGet(URL) .responsePattern( new ResponsePattern("x=(\\d+)") { @Override public void onMatch(RestCall restCall, Matcher m) throws RestCallException { xList.add(Integer.parseInt(m.group(1))); } @Override public void onNoMatch(RestCall restCall) throws RestCallException { throw new RestCallException("No X's found!"); } } ) .responsePattern( new ResponsePattern("y=(\\S+)") { @Override public void onMatch(RestCall restCall, Matcher m) throws RestCallException { yList.add(m.group(1)); } @Override public void onNoMatch(RestCall restCall) throws RestCallException { throw new RestCallException("No Y's found!"); } } ) .getResponseAsString();

Using response patterns does not affect the functionality of any of the other methods used to retrieve the response such as RestCall.getResponseAsString() or RestCall.getResponse(Class).
HOWEVER, if you want to retrieve the entire text of the response from inside the match methods, use RestCall.getCapturedResponse() since this method will not absorb the response for those other methods.

9.5 - Piping Response Output

The RestCall class provides various convenience pipeTo() methods to pipe output to output streams and writers.

If you want to pipe output without any intermediate buffering, you can use the RestCall.byLines() method. This will cause the output to be piped and flushed after every line. This can be useful if you want to display the results in real-time from a long running process producing output on a REST call.

Example:

// Pipe output from REST call to System.out in real-time. restClient.doPost(URL).byLines().pipeTo(new PrintWriter(System.out)).run();

9.6 - Debugging

Use the RestClientBuilder.debug() method to enable logging for HTTP requests made from the client.

Under-the-covers, this is simply a shortcut for adding the RestCallLogger.DEFAULT interceptor to the client.
This causes the following output to be generated by the Java org.apache.juneau.rest.client logger at WARNING level:

=== HTTP Call (outgoing) ======================================================= === REQUEST === POST http://localhost:10000/testUrl HTTP/1.1 ---request headers--- Debug: true No-Trace: true Accept: application/json ---request entity--- Content-Type: application/json ---request content--- {"foo":"bar","baz":123} === RESPONSE === HTTP/1.1 200 OK ---response headers--- Content-Type: application/json;charset=utf-8 Content-Length: 21 Server: Jetty(8.1.0.v20120127) ---response content--- {"message":"OK then"} === END ========================================================================

This setting also causes a Debug: true header value to trigger logging of the request on the server side as well.

=== HTTP Request (incoming) ==================================================== HTTP POST /testUrl ---Headers--- Host: localhost:10000 Transfer-Encoding: chunked Accept: application/json Content-Type: application/json User-Agent: Apache-HttpClient/4.5 (Java/1.6.0_65) Connection: keep-alive Debug: true Accept-Encoding: gzip,deflate ---Default Servlet Headers--- ---Body--- {"foo":"bar","baz":123} === END ========================================================================

9.7 - Logging

Use the RestClientBuilder.logTo(Level,Logger) and RestCall.logTo(Level,Logger) methods to log HTTP calls.
These methods will cause the HTTP request and response headers and body to be logged to the specified logger.

Example:

// Log the HTTP request/response to the specified logger. int rc = restClient.doGet(URL).logTo(INFO, getLogger()).run();

The method call is ignored if the logger level is below the specified level.

Customized logging can be handled by sub-classing the RestCallLogger class and using the RestCall.interceptor(RestCallInterceptor) method.

9.8 - Interceptors

The RestClientBuilder.interceptors(RestCallInterceptor...) and RestCall.interceptor(RestCallInterceptor) methods can be used to intercept responses during specific connection lifecycle events.

The RestCallLogger class is an example of an interceptor that uses the various lifecycle methods to log HTTP requests.

/** * Specialized interceptor for logging calls to a log file. */ public class RestCallLogger extends RestCallInterceptor { private Level level; private Logger log; /** * Constructor. * * @param level The log level to log messages at. * @param log The logger to log to. */ protected RestCallLogger(Level level, Logger log) { this.level = level; this.log = log; } @Override /* RestCallInterceptor */ public void onInit(RestCall restCall) { if (log.isLoggable(level)) restCall.captureResponse(); } @Override /* RestCallInterceptor */ public void onConnect(RestCall restCall, int statusCode, HttpRequest req, HttpResponse res) { // Do nothing. } @Override /* RestCallInterceptor */ public void onRetry(RestCall restCall, int statusCode, HttpRequest req, HttpResponse res) { if (log.isLoggable(level)) log.log(level, MessageFormat.format("Call to {0} returned {1}. Will retry.", req.getRequestLine().getUri(), statusCode)); } @Override /* RestCallInterceptor */ public void onClose(RestCall restCall) throws RestCallException { try { if (log.isLoggable(level)) { String output = restCall.getCapturedResponse(); StringBuilder sb = new StringBuilder(); HttpUriRequest req = restCall.getRequest(); HttpResponse res = restCall.getResponse(); if (req != null) { sb.append("\n=== HTTP Call (outgoing) ========================================================="); sb.append("\n=== REQUEST ===\n").append(req); sb.append("\n---request headers---"); for (Header h : req.getAllHeaders()) sb.append("\n").append(h); if (req instanceof HttpEntityEnclosingRequestBase) { sb.append("\n---request entity---"); HttpEntityEnclosingRequestBase req2 = (HttpEntityEnclosingRequestBase)req; HttpEntity e = req2.getEntity(); if (e == null) sb.append("\nEntity is null"); else { if (e.getContentType() != null) sb.append("\n").append(e.getContentType()); if (e.getContentEncoding() != null) sb.append("\n").append(e.getContentEncoding()); if (e.isRepeatable()) { try { sb.append("\n---request content---\n").append(EntityUtils.toString(e)); } catch (Exception ex) { throw new RuntimeException(ex); } } } } } if (res != null) { sb.append("\n=== RESPONSE ===\n").append(res.getStatusLine()); sb.append("\n---response headers---"); for (Header h : res.getAllHeaders()) sb.append("\n").append(h); sb.append("\n---response content---\n").append(output); sb.append("\n=== END ========================================================================"); } log.log(level, sb.toString()); } } catch (IOException e) { log.log(Level.SEVERE, e.getLocalizedMessage(), e); } } }

9.9 - Serverless Unit Testing

The MockRest class is used for performing serverless unit testing of REST interfaces.

Example:

public class MockTest { // Our REST resource to test. @RestResource(serializers=SimpleJsonSerializer.class, parsers=JsonParser.class) public static class MyRest { @RestMethod(name=PUT, path="/String") public String echo(@Body String body) { return body; } } @Test public void testEcho() throws Exception { MockRest .create(MyRest.class) .put("/String", "'foo'") .execute() .assertStatus(200) .assertBody("'foo'"); } }

The RestClientBuilder.mockHttpConnection(MockHttpConnection) method is used to associate a MockRest with a RestClient to allow for serverless testing of clients.

Example:

@Test public void testClient() throws Exception { MockRest mr = MockRest.create(MyRest.class); RestClient rc = RestClient.create().mockHttpConnection(mr).build(); assertEquals("'foo'", rc.doPut("/String", "'foo'").getResponseAsString()); }

Mocked connections can also be used for serverless testing of remote resources and interfaces.

Example:

// Our remote resource to test. @RemoteResource public interface MyRemoteInterface { @RemoteMethod(httpMethod="GET", path="/echoQuery") public int echoQuery(@Query(name="id") int id); } // Our mocked-up REST interface to test against. @RestResource public class MyRest { @RestMethod(name=GET, path="/echoQuery") public int echoQuery(@Query("id") String id) { return id; } } @Test public void testProxy() { MockRest mr = MockRest.create(MyRest.class); MyRemoteInterface r = RestClient .create() .mockHttpConnection(mr) .build() .getRemoteResource(MyRemoteInterface.class); assertEquals(123, r.echoQuery(123)); }

9.10 - Other Useful Methods

The RestClientBuilder.rootUrl(Object) method can be used to specify a root URL on all requests so that you don't have to use absolute paths on individual calls.

// Create a rest client with a root URL RestClient rc = RestClient.create().rootUrl("http://localhost:9080/foobar").build(); String r = rc.doGet("/baz").getResponseAsString(); // Gets "http://localhost:9080/foobar/baz"

The RestClientBuilder.set(String,Object) method can be used to set serializer and parser properties.
For example, if you're parsing a response into POJOs and you want to ignore fields that aren't on the POJOs, you can use the BeanContext.BEAN_ignoreUnknownBeanProperties property.

// Create a rest client that ignores unknown fields in the response RestClient rc = RestClient.create() .set(BEAN_ignoreUnknownBeanProperties, true) // or .ignoreUnknownBeanProperties(true) .build(); MyPojo myPojo = rc.doGet(URL).getResponse(MyPojo.class);

The RestCall.retryable(int,long,RetryOn) method can be used to automatically retry requests on failures.
This can be particularly useful if you're attempting to connect to a REST resource that may be in the process of still initializing.

// Create a rest call that retries every 10 seconds for up to 30 minutes as long as a connection fails // or a 400+ is received. restClient.doGet(URL) .retryable(180, 10000, RetryOn.DEFAULT) .run();

10 - juneau-microservice-server

Maven Dependency

<dependency> <groupId>org.apache.juneau</groupId> <artifactId>juneau-microservice-server</artifactId> <version>7.2.1</version> </dependency>

Java Library

juneau-microservice-server-7.2.1.jar

OSGi Module

org.apache.juneau.microservice.server_7.2.1.jar

Microservice Starter Project

my-microservice.zip

Juneau Microservice is an API for creating stand-alone executable jars that can be used to start lightweight configurable REST interfaces with all the power of the Juneau REST server and client APIs.

10.1 - Microservice Introduction

The Microservice API consists of a combination of the Juneau Core, Server, and Client APIs and an embedded Eclipse Jetty Servlet Container.
It includes all libraries needed to execute in a Java 1.7+ environment.

Features include:

  • An out-of-the-box zipped Eclipse project to get started quickly.
  • Packaged as a simple executable jar and configuration file.
  • All the power of the Juneau ecosystem for defining REST servlets and clients with the ability to serialize and parse POJOs as HTML, JSON, XML, RDF, URL-Encoding, and others.
  • An extensible API that allows you to hook into various lifecycle events.
  • Simple-to-use APIs for accessing manifest file entries, command-line arguments, and external configuration file properties.
  • Predefined REST resources for configuring microservice and accessing log files.

The juneau-microservice-server library consists of the following classes:

  • Microservice - Defines basic lifecycle methods for microservices in general.
    • RestMicroservice - Defines additional lifecycle methods for REST microservices.
      Starts up an externally-configured Jetty server, registers servlets, and sets up other features such as logging.

10.2 - Getting Started

The my-microservice.zip file is a zipped eclipse project that includes everything you need to create a REST microservice in an Eclipse workspace.

10.2.1 - Installing in Eclipse

Follow these instructions to create a new template project in Eclipse.

  1. Download the latest microservice-project zip file (e.g. my-microservice.zip).
  2. In your Eclipse workspace, go to File -> Import -> General -> Existing Projects into Workspace and select the zip file and click Finish.

  3. In your workspace, you should now see the following project:

The important elements in this project are:

  • RootResources.java - The top-level REST resource.
    This class routes HTTP requests to child resources:

    @RestResource( path="/", title="My Microservice", description="Top-level resources page", htmldoc=@HtmlDoc( widgets={ ContentTypeMenuItem.class, StyleMenuItem.class }, navlinks={ "options: servlet:/?method=OPTIONS" } ), children={ HelloWorldResource.class, ConfigResource.class, LogsResource.class } ) public class RootResources extends BasicRestServletJenaGroup { // No code }

  • my-microservice.cfg - The external configuration file.
    Contains various useful settings.
    Can be used for your own resource configurations.

    #======================================================================================================================= # Basic configuration file for REST microservices # Subprojects can use this as a starting point. #======================================================================================================================= # What to do when the config file is saved. # Possible values: # NOTHING - Don't do anything. (default) # RESTART_SERVER - Restart the Jetty server. # RESTART_SERVICE - Shutdown and exit with code '3'. saveConfigAction = RESTART_SERVER #======================================================================================================================= # Jetty settings #======================================================================================================================= [Jetty] # Path of the jetty.xml file used to configure the Jetty server. config = jetty.xml # Resolve Juneau variables in the jetty.xml file. resolveVars = true # 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. # The resulting available port gets set as the system property "availablePort" which can be referenced in the # jetty.xml file as "$S{availablePort}" (assuming resolveVars is enabled). port = 10000,0,0,0 #======================================================================================================================= # REST settings #======================================================================================================================= [REST] # Stylesheet to use for HTML views. # The default options are: # - servlet:/styles/juneau.css # - servlet:/styles/devops.css # Other stylesheets can be referenced relative to the servlet package or working directory. stylesheet = servlet:/styles/devops.css #======================================================================================================================= # Console settings #======================================================================================================================= [Console] enabled = true # List of available console commands. # These are classes that implements ConsoleCommand that allow you to submit commands to the microservice via # the console. # When listed here, the implementations must provide a no-arg constructor. # They can also be provided dynamically by overriding the Microservice.createConsoleCommands() method. commands = org.apache.juneau.microservice.console.ExitCommand, org.apache.juneau.microservice.console.RestartCommand, org.apache.juneau.microservice.console.HelpCommand #======================================================================================================================= # Logger settings #----------------------------------------------------------------------------------------------------------------------- # See FileHandler Java class for details. #======================================================================================================================= [Logging] ... #======================================================================================================================= # System properties #----------------------------------------------------------------------------------------------------------------------- # These are arbitrary system properties that are set during startup. #======================================================================================================================= [SystemProperties] # Configure Jetty for StdErrLog Logging # org.eclipse.jetty.util.log.class = org.eclipse.jetty.util.log.StrErrLog # Configure Jetty to log using java-util logging org.eclipse.jetty.util.log.class = org.apache.juneau.microservice.JettyLogger # Jetty logging level # Possible values: ALL, DEBUG, INFO, WARN, OFF org.eclipse.jetty.LEVEL = WARN derby.stream.error.file = $C{Logging/logDir}/derby-errors.log

  • jetty.xml - The Jetty configuration file.
    A bare-bones config file that can be extended to use any Jetty features.

    <Configure id="ExampleServer" class="org.eclipse.jetty.server.Server"> <Set name="connectors"> <Array type="org.eclipse.jetty.server.Connector"> <Item> <New class="org.eclipse.jetty.server.ServerConnector"> <Arg> <Ref refid="ExampleServer"/> </Arg> <Set name="port">$S{availablePort,8080}</Set> </New> </Item> </Array> </Set> <New id="context" class="org.eclipse.jetty.servlet.ServletContextHandler"> <Set name="contextPath">/</Set> <Call name="addServlet"> <Arg>org.apache.juneau.microservice.sample.RootResources</Arg> <Arg>/*</Arg> </Call> <Set name="sessionHandler"> <New class="org.eclipse.jetty.server.session.SessionHandler"/> </Set> </New> <Set name="handler"> <New class="org.eclipse.jetty.server.handler.HandlerCollection"> <Set name="handlers"> <Array type="org.eclipse.jetty.server.Handler"> <Item> <Ref refid="context"/> </Item> <Item> <New class="org.eclipse.jetty.server.handler.DefaultHandler"/> </Item> </Array> </Set> </New> </Set> <Set name="requestLog"> <New id="RequestLogImpl" class="org.eclipse.jetty.server.NCSARequestLog"> <Set name="filename"><Property name="jetty.logs" default="$C{Logging/logDir,logs}"/>/jetty-requests.log</Set> <Set name="filenameDateFormat">yyyy_MM_dd</Set> <Set name="LogTimeZone">GMT</Set> <Set name="retainDays">90</Set> <Set name="append">false</Set> <Set name="LogLatency">true</Set> </New> </Set> <Get name="ThreadPool"> <Set name="minThreads" type="int">10</Set> <Set name="maxThreads" type="int">100</Set> <Set name="idleTimeout" type="int">60000</Set> <Set name="detailedDump">true</Set> </Get> </Configure>

At this point, you're ready to start the microservice from your workspace.

10.2.2 - Running in Eclipse

The my-microservice.launch file is already provided to allow you to quickly start your new microservice.

Go to Run -> Run Configurations -> Java Application -> my-microservice and click Run.
In your console view, you should see the following output:

Running class 'RestMicroservice' using config file 'my-microservice.cfg'. Server started on port 10000 List of available commands: exit -- Shut down service restart -- Restarts service help -- Commands help >

Now open your browser and point to http://localhost:10000. You should see the following:

http://localhost:10000

You have started a REST interface on port 10000.
You can enter the command exit to shut it down.

10.2.3 - Building and Running from Command-Line

The pom.xml file is a basic Maven build script for creating your microservice as an executable uber-jar.

The easiest way to build your microservice is to run the following from the project root.

mvn clean install

Your target directory should now contain the following files:

  • my-microservice-1.0.jar
  • my-microservice.cfg
  • jetty.xml

To start from a command line, run the following command from inside your target directory:

java -jar my-microservice-1.0.jar

You should see the following console output:

Running class 'RestMicroservice' using config file 'my-microservice.cfg'. Server started on port 10000 List of available commands: exit -- Shut down service restart -- Restarts service help -- Commands help >

If you get this error message: java.net.BindException: Address already in use, then this microservice is already running elsewhere and so it cannot bind to port 10000.

10.3 - Manifest File

The generated META-INF/MANIFEST.MF file is used to describe the microservice.
If you open it, you'll see the following:

Main-Class: org.apache.juneau.microservice.RestMicroservice Main-ConfigFile: my-microservice.cfg

The Main-Class entry is the standard manifest entry describing the entry point for the executable jar.
In most cases, this value will always be org.apache.juneau.microservice.RestMicroservice.
However, it is possible to extend this class or implement your own microservice, in which case you'll need to modify this value to point to the new class.

The Main-ConfigFile entry points to the location of an external configuration file for our microservice.

In addition to these predefined manifest entries, you can add your own particular entries to the manifest file and access them through the Manifest API described next.

10.3.1 - Manifest API

The Microservice.getManifest() method is a static method that can be used to retrieve the manifest file as a ManifestFile.

// Get Main-Class from manifest file. String mainClass = Microservice.getInstance().getManifest().getString("Main-Class", "unknown");

The ManifestFile class extends ObjectMap, making it possible to retrieve entries as a wide variety of object types such as java primitives, arrays, collections, maps, or even POJOs serialized as JSON.

10.4 - Config

The microservice config file is an external INI-style configuration file that is used to configure your microservice.

See Also:

10.4.1 - Config File API

There are 3 primary ways of getting access to the config file.

  • Microservice.getConfig()
    Any initialization-time variables can be used.
  • RestContext.getConfig()
    Any initialization-time variables can be used.
    Example usage:

    #------------------------------- # Properties for MyHelloResource #------------------------------- [MyHelloResource] greeting = Hello world!

    @RestResource(...) public class MyHelloResource extends BasicRestServlet { // Access config file when initializing fields. private String greeting = getConfig().getString("MyHelloResource/greeting"); // Or access config file in servlet init method. @Override /* Servlet */ public void init() { String greeting = getConfig().getString("MyHelloResource/greeting"); } }

    Additional user-defined variables can be defined at this level by adding a HookEvent.INIT hook method and using the RestContextBuilder.vars(Class...) method.

  • RestRequest.getConfig() - An instance method to access it from inside a REST method.
    Any initialization-time or request-time variables can be used.
    Example usage:

    #----------------------------- # Contents of microservice.cfg #----------------------------- [MyHelloResource] greeting = Hello $RP{person}! localizedGreeting = $L{HelloMessage,$RP{person}}

    #--------------------------------- # Contents of MyHelloResource.java #--------------------------------- @RestResource( path="/hello", messages="nls/Messages", ... ) public class MyHelloResource extends BasicRestServlet { /** Standard hello message. */ @RestMethod(name=GET, path="/{person}") public String sayHello(RestRequest req) { return req.getConfig().getString("MyHelloResource/greeting"); } /** Hello message in users language. */ @RestMethod(name=GET, path="/localized/{person}") public String sayLocalizedHello(RestRequest req) { return req.getConfig().getString("MyHelloResource/localizedGreeting"); } }

    #--------------------------------------- # Contents of nls/Messages_en.properties #--------------------------------------- MyHelloResource.HelloMessage = Hello {0}!

    Additional user-defined variables can be defined at this level by overriding the RestContextBuilder.vars(Class...) method.

That sayLocalizedHello() example might need some explanation since there's a lot going on there.
Here's what happens when an HTTP call is made to GET /hello/localized/Bob:

  1. The HTTP call matches the /hello path on the MyHelloResource class.
  2. The HTTP call matches the /localized/{person} path on the sayLocalizedHello() method.
  3. The request attribute person gets assigned the value "Bob".
  4. The call to req.getConfig().getString("MyHelloResource/localizedGreeting") finds the value "$L{HelloMessage,$RP{person}}".
  5. The arguments in the $L{} variable get resolved, resulting in "$L{HelloMessage,Bob}".
  6. The $L{} variable gets resolved to the message "Hello {0}!" in the localized properties file of the servlet based on the Accept-Language header on the request.
  7. The arguments get replaced in the message resulting in "Hello Bob!".
  8. The resulting message "Hello Bob!" is returned as a POJO to be serialized to whatever content type was specified on the Accept header on the request.

This particular example is needlessly complex, but it gives an idea of how variables can be used recursively to produce sophisticated results

10.5 - Resource Classes

Now let's take a look at the resource classes themselves.
The top-level page...

http://localhost:10000

...is generated by this class...

@RestResource( path="/", title="My Microservice", description="Top-level resources page", htmldoc=@HtmlDoc( navlinks={ "options: servlet:/?method=OPTIONS" } ), children={ HelloWorldResource.class, ConfigResource.class, LogsResource.class } ) public class RootResources extends BasicRestServletJenaGroup { // No code! }

  • The title and description annotations define the titles on the page.
    These can be globalized using $L{...} variables, or by defining specially-named properties in the properties file for the resource.
  • In this case, the path annotation defines the context root of your application since it was not specified in the manifest or config file.
    Therefore, this resource is mapped to http://localhost:10000.
  • The children annotation make up the list of child resources.
    These child resources can be anything that extends from Servlet, although usually they will be subclasses of BasicRestServlet or other resource groups.

If you click the helloWorld link in your application, you'll get a simple hello world message:

http://localhost:10000/helloWorld

...which is generated by this class...

@RestResource( path="/helloWorld", title="Hello World example", description="Simplest possible REST resource" ) public class HelloWorldResource extends BasicRestServlet { @RestMethod(name=GET, path="/*") public String sayHello() { return "Hello world!"; } }

10.6 - Predefined Resource Classes

The following predefined resource classes are also provided for easy inclusion into your microservice:

10.7 - RestMicroservice

The RestMicroservice class is the main application entry-point for REST microservices.

The class hierarchy is:

  • Microservice - Abstract class that defines simple start/stop methods and access to the manifest file, config file, and arguments.
    • RestMicroservice - Specialized microservice for starting up REST interfaces using Jetty and specifying REST servlets through the manifest file or config file.

Refer to the Javadocs for these class for more information.

10.7.1 - Extending RestMicroservice

This example shows how the RestMicroservice class can be extended to implement lifecycle listener methods or override existing methods.
We'll create a new class com.foo.SampleCustomRestMicroservice.

First, the manifest file needs to be modified to point to our new microservice:

Main-Class: com.foo.SampleCustomRestMicroservice

Then we define the following class:

/** * 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. */ public class SampleCustomRestMicroservice extends RestMicroservice { /** * Must implement a main method and call start()! */ public static void main(String[] args) throws Exception { new SampleCustomRestMicroservice(args).start().join(); } /** * Must implement a constructor! * * @param args Command line arguments. * @throws Exception */ public SampleCustomRestMicroservice(String[] args) throws Exception { super(args); }

The microservice APIs provide several useful methods that can be used or extended.

See Also:

10.8 - UI Customization

The Microservice project contains a files/htdocs working directly folder with predefined stylesheets and images.

These files can be used to tailor the look-and-feel of your microservice.

http://localhost:10000/helloWorld

The REST configuration section of your microservice configuration file can be used to tailor the header and footer on the pages:

#======================================================================================================================= # REST settings #======================================================================================================================= [REST] staticFiles = htdocs:files/htdocs # Stylesheet to use for HTML views. theme = servlet:/htdocs/themes/devops.css headerIcon = servlet:/htdocs/images/juneau.png headerLink = http://juneau.apache.org footerIcon = servlet:/htdocs/images/asf.png footerLink = http://www.apache.org favicon = $C{REST/headerIcon} header = <a href='$U{$C{REST/headerLink}}'> <img src='$U{$C{REST/headerIcon}}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/> </a> footer = <a href='$U{$C{REST/footerLink}}'> <img src='$U{$C{REST/footerIcon}}' style='float:right;padding-right:20px;height:32px'/> </a>

The BasicRestConfig interface (which defines the default settings for BasicRestServlet pulls in this information using $C and $U variables:

@RestResource( ... // HTML-page specific settings htmldoc=@HtmlDoc( // Default page header contents. header={ "<h1>$R{resourceTitle}</h1>", // Use @RestResource(title) "<h2>$R{methodSummary,resourceDescription}</h2>", // Use either @RestMethod(summary) or @RestResource(description) "$C{REST/header}" // Extra header HTML defined in external config file. }, // 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). stylesheet="$C{REST/theme,servlet:/htdocs/themes/devops.css}", // Default contents to add to the <head> section of the HTML page. // Use it to add a favicon link to the page. head={ "<link rel='icon' href='$U{$C{REST/favicon}}'/>" }, // No default page footer contents. // Can be overridden from external config file. footer="$C{REST/footer}" ), // Optional external configuration file. config="$S{juneau.configFile}", // 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. staticFiles="$C{REST/staticFiles}" ) public interface BasicRestConfig {}

Note that the files/htdocs directory is mapped to "servlet:/htdocs" using the staticFiles setting. This allows those files to be served up through the servlet through the URL "/[servlet-path]/htdocs"

The theme files are externally accessible and can be modified to produce any look-and-feel you desire. The microservice still works without the files directory. An embedded devops.css is included in the jar as a default spreadsheet.

If you're testing out changes in the theme stylesheets, you may want to set the following system property that prevents caching of those files so that you don't need to restart the microservice each time a change is made:

#======================================================================================================================= # System properties #----------------------------------------------------------------------------------------------------------------------- # These are arbitrary system properties that are set during startup. #======================================================================================================================= [SystemProperties] # Disable classpath resource caching. # Useful if you're attached using a debugger and you're modifying classpath resources while running. RestContext.useClasspathResourceCaching.b = false

11 - juneau-examples-core

Archive File

juneau-examples-core-7.2.1.zip

The juneau-examples-core project contains various code examples for using the core APIs.

The project project can be loaded into your workspace by importing the juneau-examples-core-7.2.1.zip file.

juneau-examples-core install instructions

Download the juneau-examples-core-7.2.1.zip file from the downloads page (located in the binaries) and import it into your workspace as an existing project:

Select the archive file and import the project:

Once loaded, you should see the following project structure:

The Core library samples are currently a work-in-progress so there's not much here yet. This section will be updated as new code is added.

12 - juneau-examples-rest

Archive File

juneau-examples-rest-7.2.1.zip

The juneau-examples-rest project includes everything you need to start the Samples REST microservice in an Eclipse workspace.

This project is packaged as a Juneau Microservice project that allows REST resources to be started using embedded Jetty.

juneau-examples-rest install instructions

Download the juneau-examples-rest-7.2.1.zip file from the downloads page (located in the binaries) and import it into your workspace as an existing project:

Select the archive file and import the project:

Once loaded, you should see the following project structure:

The microservice can be started from the juneau-examples-rest.launch file. It will start up the microservice on port 10000 which you can then view through a browser:

http://localhost:10000

12.1 - RootResources

The RootResources class is the main page for the REST microservice. It serves as the jumping-off point for the other resources.

The class hierarchy for this class is:

Pointing a browser to the resource shows the following:

http://localhost:10000

The RootResources class can also be defined as a servlet in a web.xml file:

<web-app version='2.3'> <servlet> <servlet-name>RootResources</servlet-name> <servlet-class>org.apache.juneau.rest.samples.RootResources</servlet-class> </servlet> <servlet-mapping> <servlet-name>RootResources</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> </web-app>

The RootResources class consists entirely of annotations:

RootResources.java

/** * Sample REST resource showing how to implement a "router" resource page. */ @RestResource( path="/", title="Root resources", description="Example of a router resource page.", htmldoc=@HtmlDoc( widgets={ PoweredByApache.class, ContentTypeMenuItem.class, StyleMenuItem.class }, navlinks={ "options: ?method=OPTIONS", "$W{ContentTypeMenuItem}", "$W{StyleMenuItem}", "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java" }, aside={ "<div style='max-width:400px' class='text'>", " <p>This is an example of a 'router' page that serves as a jumping-off point to child resources.</p>", " <p>Resources can be nested arbitrarily deep through router pages.</p>", " <p>Note the <span class='link'>options</span> link provided that lets you see the generated swagger doc for this page.</p>", " <p>Also note the <span class='link'>sources</span> link on these pages to view the source code for the page.</p>", " <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>", " <p>Other features (such as this aside) are added through annotations.</p>", "</div>" }, footer="$W{PoweredByApache}" ), properties={ // For testing purposes, we want to use single quotes in all the serializers so it's easier to do simple // String comparisons. // You can apply any of the Serializer/Parser/BeanContext settings this way. @Property(name=SERIALIZER_quoteChar, value="'") }, children={ HelloWorldResource.class, PetStoreResource.class, RequestEchoResource.class, SampleRrpcServlet.class, PhotosResource.class, DtoExamples.class, SqlQueryResource.class, ConfigResource.class, LogsResource.class, DebugResource.class, ShutdownResource.class } ) public class RootResources extends BasicRestServletJenaGroup { // No code! }

The children annotation defines the child resources of this router resource.
These are resources whose paths are direct decendents to the parent resource.

Child resources must be annotated with the @RestResource(path) annotation to identify the subpath of the child.
Children CAN extend from BasicRestServlet, but it is not a requirement.

Child resources can also be defined programmatically by using the RestContextBuilder.children(Class[]) method.

Note that these router pages can be arbitrarily nested deep. You can define many levels of router pages for arbitrarily hierarchical REST interfaces.

Let's step back and describe what's going on here:
During servlet initialization of the RootResources object, the toolkit looks for the @RestResource(children) annotation.
If it finds it, it instantiates instances of each class and recursively performs servlet initialization on them.
It then associates the child resource with the parent by the name specified by the @RestResource(path) annotation on the child class.
When a request for the child URL (/helloWorld) is received, the RootResources servlet gets the request and sees that the URL remainder matches one of its child resources.
It then forwards the request to the child resource for processing.
The request passed to the child resource is the same as if the child resource had been deployed independently (e.g. path-info, resource-URI, and so forth).

12.2 - HelloWorldResource

The HelloWorldResource class is a simple resource that prints a "Hello world!" message.

HelloWorldResource.java

/** * Sample REST resource that prints out a simple "Hello world!" message. */ @RestResource( title="Hello World", description="An example of the simplest-possible resource", path="/helloWorld", htmldoc=@HtmlDoc( aside={ "<div style='max-width:400px' class='text'>", " <p>This page shows a resource that simply response with a 'Hello world!' message</p>", " <p>The POJO serialized is a simple String.</p>", "</div>" } ) ) public class HelloWorldResource implements BasicRestConfig { /** GET request handler */ @RestMethod(name=GET, path="/*") public String sayHello() { return "Hello world!"; } }

Notice that in this case we're not extending from RestServlet.
We are however implementing BasicRestConfig which is a no-op interface that defines a default @RestResource annotation with all the serializers, parsers, and configuration defined on the BasicRestServlet class.

The only difference between implementing BasicRestConfig and extending from BasicRestServlet is that the latter provides the following additional features:

  • A default OPTIONS method.
  • It can be deployed like any servlet.

All other examples in this project extend from BasicRestServlet so that they provide automatic OPTIONS page support.

Pointing a browser to the resource shows the following:

http://localhost:10000/helloWorld

Using the special &Accept=text/json and &plainText=true parameters allows us to see this page rendered as JSON:

http://localhost:10000/helloWorld?Accept=text/json&plainText=true

12.3 - PetStoreResource

The PetStoreResource class provides examples for creating a Swagger-based interface.

PetStoreResource.java

@RestResource( path="/petstore", title="Petstore application", description= { "This is a sample server Petstore server based on the Petstore sample at Swagger.io.", "You can find out more about Swagger at <a class='link' href='http://swagger.io'>http://swagger.io</a>.", }, htmldoc=@HtmlDoc( widgets={ ContentTypeMenuItem.class, ThemeMenuItem.class, }, navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS", "$W{ContentTypeMenuItem}", "$W{ThemeMenuItem}", "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/petstore/$R{servletClassSimple}.java" }, head={ "<link rel='icon' href='$U{servlet:/htdocs/cat.png}'/>" // Add a cat icon to the page. }, header={ "<h1>$R{resourceTitle}</h1>", "<h2>$R{methodSummary}</h2>", "$C{PetStore/headerImage}" }, aside={ "<div style='max-width:400px' class='text'>", " <p>This page shows a standard nested REST resource.</p>", " <p>It shows how different properties can be rendered on the same bean in different views.</p>", " <p>It also shows examples of HtmlRender classes and @BeanProperty(format) annotations.</p>", " <p>It also shows how the Queryable converter and query widget can be used to create searchable interfaces.</p>", "</div>" } ), properties= { // Resolve recursive references when showing schema info in the swagger. @Property(name=SWAGGERUI_resolveRefsMaxDepth, value="99") }, swagger=@ResourceSwagger("$F{PetStoreResource.json}"), staticFiles={"htdocs:htdocs"} ) public class PetStoreResource extends BasicRestServletJena { private PetStore store; @RestHook(INIT) public void initDatabase(RestContextBuilder builder) throws Exception { store = new PetStore().init(); } @RestMethod( name=GET, path="/", summary="Navigation page" ) public ResourceDescriptions getTopPage() { return new ResourceDescriptions() .append("pet", "All pets in the store") .append("store", "Orders and inventory") .append("user", "Petstore users") ; } //------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- // Pets //------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- @RestMethod( name=GET, path="/pet", summary="All pets in the store", swagger=@MethodSwagger( tags="pet", parameters={ Queryable.SWAGGER_PARAMS } ), bpx="Pet: tags", htmldoc=@HtmlDoc( widgets={ QueryMenuItem.class, AddPetMenuItem.class }, navlinks={ "INHERIT", // Inherit links from class. "[2]:$W{QueryMenuItem}", // Insert QUERY link in position 2. "[3]:$W{AddPetMenuItem}" // Insert ADD link in position 3. } ), converters={Queryable.class} ) public Collection<Pet> getPets() throws NotAcceptable { return store.getPets(); } @RestMethod( name=GET, path="/pet/{petId}", summary="Find pet by ID", description="Returns a single pet", swagger=@MethodSwagger( tags="pet", value={ "security:[ { api_key:[] } ]" } ) ) public Pet getPet( @Path( name="petId", description="ID of pet to return", example="123" ) long petId ) throws IdNotFound, NotAcceptable { return store.getPet(petId); } @RestMethod( summary="Add a new pet to the store", swagger=@MethodSwagger( tags="pet", value={ "security:[ { petstore_auth:['write:pets','read:pets'] } ]" } ) ) public Ok postPet( @Body(description="Pet object to add to the store") PetCreate pet ) throws IdConflict, NotAcceptable, UnsupportedMediaType { store.create(pet); return OK; } @RestMethod( name=PUT, path="/pet/{petId}", summary="Update an existing pet", swagger=@MethodSwagger( tags="pet", value={ "security:[ { petstore_auth: ['write:pets','read:pets'] } ]" } ) ) public Ok updatePet( @Body(description="Pet object that needs to be added to the store") PetUpdate pet ) throws IdNotFound, NotAcceptable, UnsupportedMediaType { store.update(pet); return OK; } @RestMethod( name=GET, path="/pet/{petId}/edit", summary="Pet edit page", swagger=@MethodSwagger( tags="pet", value={ "security:[ { petstore_auth:['write:pets','read:pets'] } ]" } ) ) public Div editPetPage( @Path( name="petId", description="ID of pet to return", example="123" ) long petId ) throws IdConflict, NotAcceptable, UnsupportedMediaType { Pet pet = getPet(petId); return div( form().id("form").action("servlet:/pet/" + petId).method(POST).children( table( tr( th("Id:"), td(input().name("id").type("text").value(petId).readonly(true)), td(new Tooltip("(?)", "The name of the pet.", br(), "e.g. 'Fluffy'")) ), tr( th("Name:"), td(input().name("name").type("text").value(pet.getName())), td(new Tooltip("(?)", "The name of the pet.", br(), "e.g. 'Fluffy'")) ), tr( th("Species:"), td( select().name("species").children( option("cat"), option("dog"), option("bird"), option("fish"), option("mouse"), option("rabbit"), option("snake") ).choose(pet.getSpecies()) ), td(new Tooltip("(?)", "The kind of animal.")) ), tr( th("Price:"), td(input().name("price").type("number").placeholder("1.0").step("0.01").min(1).max(100).value(pet.getPrice())), td(new Tooltip("(?)", "The price to charge for this pet.")) ), tr( th("Tags:"), td(input().name("tags").type("text").value(Tag.asString(pet.getTags()))), td(new Tooltip("(?)", "Arbitrary textual tags (comma-delimited).", br(), "e.g. 'fluffy,friendly'")) ), tr( th("Status:"), td( select().name("status").children( option("AVAILABLE"), option("PENDING"), option("SOLD") ).choose(pet.getStatus()) ), td(new Tooltip("(?)", "The current status of the animal.")) ), tr( td().colspan(2).style("text-align:right").children( button("reset", "Reset"), button("button","Cancel").onclick("window.location.href='/'"), button("submit", "Submit") ) ) ).style("white-space:nowrap") ) ); } @RestMethod( name=GET, path="/pet/findByStatus", summary="Finds Pets by status", description="Multiple status values can be provided with comma separated strings.", swagger=@MethodSwagger( tags="pet", value={ "security:[{petstore_auth:['write:pets','read:pets']}]" } ) ) public Collection<Pet> findPetsByStatus( @Query( name="status", description="Status values that need to be considered for filter.", required=true, type="array", collectionFormat="csv", items=@Items( type="string", _enum="AVAILABLE,PENDING,SOLD", _default="AVAILABLE" ), example="AVALIABLE,PENDING" ) PetStatus[] status ) throws NotAcceptable { return store.getPetsByStatus(status); } @RestMethod( name=GET, path="/pet/findByTags", summary="Finds Pets by tags", description="Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.", swagger=@MethodSwagger( tags="pet", value={ "security:[ { petstore_auth:[ 'write:pets','read:pets' ] } ]" } ) ) @Deprecated public Collection<Pet> findPetsByTags( @Query( name="tags", description="Tags to filter by", required=true, example="['tag1','tag2']" ) String[] tags ) throws InvalidTag, NotAcceptable { return store.getPetsByTags(tags); } @RestMethod( name=DELETE, path="/pet/{petId}", summary="Deletes a pet", swagger=@MethodSwagger( tags="pet", value={ "security:[ { petstore_auth:[ 'write:pets','read:pets' ] } ]" } ) ) public Ok deletePet( @Header( name="api_key", description="Security API key", required=true, example="foobar" ) String apiKey, @Path( name="petId", description="Pet id to delete", example="123" ) long petId ) throws IdNotFound, NotAcceptable { store.removePet(petId); return OK; } @RestMethod( name=POST, path="/pet/{petId}/uploadImage", summary="Uploads an image", swagger=@MethodSwagger( tags="pet", value={ "security:[ { petstore_auth:[ 'write:pets','read:pets' ] } ]" } ) ) public Ok uploadImage( @Path( name="petId", description="ID of pet to update", example="123" ) long petId, @FormData( name="additionalMetadata", description="Additional data to pass to server", example="Foobar" ) String additionalMetadata, @FormData( name="file", description="file to upload", required=true, type="file" ) byte[] file ) throws NotAcceptable, UnsupportedMediaType { return OK; } //------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- // Orders //------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- @RestMethod( summary="Store navigation page", swagger=@MethodSwagger( tags="store" ) ) public ResourceDescriptions getStore() { return new ResourceDescriptions() .append("store/order", "Petstore orders") .append("store/inventory", "Petstore inventory") ; } @RestMethod( name=GET, path="/store/order", summary="Petstore orders", swagger=@MethodSwagger( tags="store" ), htmldoc=@HtmlDoc( widgets={ QueryMenuItem.class, AddOrderMenuItem.class }, navlinks={ "INHERIT", // Inherit links from class. "[2]:$W{QueryMenuItem}", // Insert QUERY link in position 2. "[3]:$W{AddOrderMenuItem}" // Insert ADD link in position 3. } ) ) public Collection<Order> getOrders() throws NotAcceptable { return store.getOrders(); } @RestMethod( name=GET, path="/store/order/{orderId}", summary="Find purchase order by ID", description="Returns a purchase order by ID.", swagger=@MethodSwagger( tags="store" ) ) public Order getOrder( @Path( name="orderId", description="ID of order to fetch", maximum="1000", minimum="101", example="123" ) long orderId ) throws InvalidId, IdNotFound, NotAcceptable { if (orderId < 101 || orderId > 1000) throw new InvalidId(); return store.getOrder(orderId); } @RestMethod( name=POST, path="/store/order", summary="Place an order for a pet", swagger=@MethodSwagger( tags="store" ), pojoSwaps={ DateSwap.ISO8601D.class } ) public Order placeOrder( @FormData( name="petId", description="Pet ID" ) long petId, @FormData( name="shipDate", description="Ship date" ) Date shipDate ) throws IdConflict, NotAcceptable, UnsupportedMediaType { CreateOrder co = new CreateOrder(petId, shipDate); return store.create(co); } @RestMethod( name=DELETE, path="/store/order/{orderId}", summary="Delete purchase order by ID", description= { "For valid response try integer IDs with positive integer value.", "Negative or non-integer values will generate API errors." }, swagger=@MethodSwagger( tags="store" ) ) public Ok deletePurchaseOrder( @Path( name="orderId", description="ID of the order that needs to be deleted", minimum="1", example="5" ) long orderId ) throws InvalidId, IdNotFound, NotAcceptable { if (orderId < 0) throw new InvalidId(); store.removeOrder(orderId); return OK; } @RestMethod( name=GET, path="/store/inventory", summary="Returns pet inventories by status", description="Returns a map of status codes to quantities", swagger=@MethodSwagger( tags="store", responses={ "200:{ 'x-example':{AVAILABLE:123} }", }, value={ "security:[ { api_key:[] } ]" } ) ) public Map<PetStatus,Integer> getStoreInventory() throws NotAcceptable { return store.getInventory(); } //------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- // Users //------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- @RestMethod( name=GET, path="/user", summary="Petstore users", bpx="User: email,password,phone", swagger=@MethodSwagger( tags="user" ) ) public Collection<User> getUsers() throws NotAcceptable { return store.getUsers(); } @RestMethod( name=GET, path="/user/{username}", summary="Get user by user name", swagger=@MethodSwagger( tags="user" ) ) public User getUser( @Path( name="username", description="The name that needs to be fetched. Use user1 for testing." ) String username ) throws InvalidUsername, IdNotFound, NotAcceptable { return store.getUser(username); } @RestMethod( summary="Create user", description="This can only be done by the logged in user.", swagger=@MethodSwagger( tags="user" ) ) public Ok postUser( @Body(description="Created user object") User user ) throws InvalidUsername, IdConflict, NotAcceptable, UnsupportedMediaType { store.add(user); return OK; } @RestMethod( name=POST, path="/user/createWithArray", summary="Creates list of users with given input array", swagger=@MethodSwagger( tags="user" ) ) public Ok createUsers( @Body(description="List of user objects") User[] users ) throws InvalidUsername, IdConflict, NotAcceptable, UnsupportedMediaType { for (User user : users) store.add(user); return OK; } @RestMethod( name=PUT, path="/user/{username}", summary="Update user", description="This can only be done by the logged in user.", swagger=@MethodSwagger( tags="user" ) ) public Ok updateUser( @Path( name="username", description="Name that need to be updated" ) String username, @Body( description="Updated user object" ) User user ) throws InvalidUsername, IdNotFound, NotAcceptable, UnsupportedMediaType { store.update(user); return OK; } @RestMethod( name=DELETE, path="/user/{username}", summary="Delete user", description="This can only be done by the logged in user.", swagger=@MethodSwagger( tags="user" ) ) public Ok deleteUser( @Path( name="username", description="The name that needs to be deleted" ) String username ) throws InvalidUsername, IdNotFound, NotAcceptable { store.removeUser(username); return OK; } @RestMethod( name=GET, path="/user/login", summary="Logs user into the system", swagger=@MethodSwagger( tags="user" ) ) public Ok login( @Query( name="username", description="The username for login", required=true, example="myuser" ) String username, @Query( name="password", description="The password for login in clear text", required=true, example="abc123" ) String password, @ResponseHeader( name="X-Rate-Limit", type="integer", format="int32", description="Calls per hour allowed by the user.", example="123" ) Value<Integer> rateLimit, Value<ExpiresAfter> expiresAfter, RestRequest req, RestResponse res ) throws InvalidLogin, NotAcceptable { if (! store.isValid(username, password)) throw new InvalidLogin(); Date d = new Date(System.currentTimeMillis() + 30 * 60 * 1000); req.getSession().setAttribute("login-expires", d); rateLimit.set(1000); expiresAfter.set(new ExpiresAfter(d)); return OK; } @ResponseHeader( name="X-Expires-After", type="string", format="date-time", description="Date in UTC when token expires", example="2012-10-21" ) public static class ExpiresAfter { private final Calendar c; public ExpiresAfter(Date d) { this.c = new GregorianCalendar(); c.setTime(d); } public Calendar toCalendar() { return c; } } @RestMethod( name=GET, path="/user/logout", summary="Logs out current logged in user session", swagger=@MethodSwagger( tags="user" ) ) public Ok logout(RestRequest req) throws NotAcceptable { req.getSession().removeAttribute("login-expires"); return OK; } }

Pointing a browser to the resource shows the following:

http://localhost:10000/petstore

Clicking the QUERY link renders the following menu pop-up complete with tooltips:

The STYLES menu item allows you to try out the other default look-and-feels:

Light look-and-feel
Dark look-and-feel

12.4 - DtoExamples

The DtoExamples resource is a resource group for demonstrating various DTO examples.

The AtomFeedResource class shows examples of the following:

Pointing a browser to the resource shows the following:

http://localhost:10000/atom

True ATOM feeds require using an Accept:text/xml header:

http://localhost:10000/atom?Accept=text/xml&plainText=true

Other languages, such as JSON are also supported:

http://localhost:10000/atom?Accept=text/json&plainText=true

AtomFeedResource.java

/** * Sample resource that shows how to generate ATOM feeds. */ @RestResource( path="/atom", title="Sample ATOM feed resource", description="Sample resource that shows how to render ATOM feeds", htmldoc=@HtmlDoc( widgets={ ContentTypeMenuItem.class, StyleMenuItem.class }, navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS", "$W{ContentTypeMenuItem}", "$W{StyleMenuItem}", "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java" } ), properties={ @Property(name=SERIALIZER_quoteChar, value="'"), @Property(name=RDF_rdfxml_tab, value="5"), @Property(name=RDF_addRootProperty, value="true") }, encoders=GzipEncoder.class ) public class AtomFeedResource extends BasicRestServletJena { private Feed feed; // The root resource object @Override /* Servlet */ public void init() { try { feed = feed("tag:juneau.sample.com,2013:1", "Juneau ATOM specification", "2013-05-08T12:29:29Z") .subtitle(text("html").text("A <em>lot</em> of effort went into making this effortless")) .links( link("alternate", "text/html", "http://www.sample.com/").hreflang("en"), link("self", "application/atom+xml", "http://www.sample.com/feed.atom") ) .generator( generator("Juneau").uri("http://juneau.apache.org/").version("1.0") ) .entries( entry("tag:juneau.sample.com,2013:1.2345", "Juneau ATOM specification snapshot", "2013-05-08T12:29:29Z") .links( link("alternate", "text/html", "http://www.sample.com/2012/05/08/juneau.atom"), link("enclosure", "audio/mpeg", "http://www.sample.com/audio/juneau_podcast.mp3").length(1337) ) .published("2013-05-08T12:29:29Z") .authors( person("James Bognar").uri(new URI("http://www.sample.com/")).email("jamesbognar@apache.org") ) .contributors( person("Barry M. Caceres") ) .content( content("xhtml") .lang("en") .base("http://www.apache.org/") .text("<div><p>[Update: Juneau supports ATOM.]</p></div>") ) ); } catch (Exception e) { throw new RuntimeException(e); } } /** * GET request handler */ @RestMethod(name=GET, path="/") public Feed getFeed() throws Exception { return feed; } /** * PUT request handler. * Replaces the feed with the specified content, and then mirrors it as the response. */ @RestMethod(name=PUT, path="/") public Feed setFeed(@Body Feed feed) throws Exception { this.feed = feed; return feed; } }

The JsonSchemaResource class shows examples of the following:

The resource consists of a pre-initialized JsonSchema object. Pointing a browser to the resource shows the following:

http://localhost:10000/jsonSchema

For true JSON-Schema, you need to specify the header Accept: text/json:

http://localhost:10000/jsonSchema?Accept=text/json&plainText=true

JsonSchemaResource.java

/** * Sample resource that shows how to serialize JSON-Schema documents. */ @RestResource( path="/jsonSchema", messages="nls/JsonSchemaResource", title="Sample JSON-Schema document", description="Sample resource that shows how to generate JSON-Schema documents", htmldoc=@HtmlDoc( widgets={ ContentTypeMenuItem.class, StyleMenuItem.class }, navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS", "$W{ContentTypeMenuItem}", "$W{StyleMenuItem}", "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java" }, aside={ "<div style='min-width:200px' class='text'>", " <p>Shows how to produce JSON-Schema documents in a variety of languages using the JSON-Schema DTOs.</p>", "</div>" } ) ) public class JsonSchemaResource extends BasicRestServletJena { private static final long serialVersionUID = 1L; private JsonSchema schema; // The schema document @Override /* Servlet */ public void init() { try { schema = new JsonSchema() .setId("http://example.com/sample-schema#") .setSchemaVersionUri("http://json-schema.org/draft-04/schema#") .setTitle("Example Schema") .setType(JsonType.OBJECT) .addProperties( new JsonSchemaProperty("firstName", JsonType.STRING), new JsonSchemaProperty("lastName", JsonType.STRING), new JsonSchemaProperty("age", JsonType.INTEGER) .setDescription("Age in years") .setMinimum(0) ) .addRequired("firstName", "lastName"); } catch (Exception e) { throw new RuntimeException(e); } } /** GET request handler */ @RestMethod(name=GET, path="/") public JsonSchema getSchema() throws Exception { return schema; } /** * PUT request handler. * Replaces the schema document with the specified content, and then mirrors it as the response. */ @RestMethod(name=PUT, path="/") public JsonSchema setSchema(@Body JsonSchema schema) throws Exception { this.schema = schema; return schema; } }

12.5 - PhotosResource

The PhotosResource class shows examples of the following:

  • How to define custom serializers and parsers at the method level. In this case, you define a serializer and parser to handle images.

The resource consists of a simple registry of images with integer IDs.

http://localhost:10000/photos

It is initialized with a single entry, which can be accessed through a GET request.

http://localhost:10000/photos/cat

PhotosResource.java

/** * Sample resource that allows images to be uploaded and retrieved. */ @RestResource( path="/photos", messages="nls/PhotosResource", title="Photo REST service", description="Sample resource that allows images to be uploaded and retrieved.", htmldoc=@HtmlDoc( navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS", "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java" }, aside={ "<div style='max-width:400px;min-width:200px' class='text'>", " <p>Shows an example of using custom serializers and parsers to create REST interfaces over binary resources.</p>", " <p>In this case, our resources are marshalled jpeg and png binary streams and are stored in an in-memory 'database' (also known as a <code>TreeMap</code>).</p>", "</div>" } ), properties={ // Make the anchor text on URLs be just the path relative to the servlet. @Property(name=HTML_uriAnchorText, value="SERVLET_RELATIVE") } ) public class PhotosResource extends BasicRestServlet { // Our cache of photos private Map<String,Photo> photos = new TreeMap<>(); @Override /* Servlet */ public void init() { try (InputStream is = getClass().getResourceAsStream("averycutecat.jpg")) { BufferedImage image = ImageIO.read(is); Photo photo = new Photo("cat", image); photos.put(photo.id, photo); } catch (IOException e) { throw new RuntimeException(e); } } /** Bean class for storing photos */ public static class Photo { private String id; BufferedImage image; Photo(String id, BufferedImage image) { this.id = id; this.image = image; } public URI getURI() throws URISyntaxException { return new URI("servlet:/" + id); } } /** GET request handler for list of all photos */ @RestMethod(name=GET, path="/", summary="Show the list of all currently loaded photos") public Collection<Photo> getAllPhotos() throws Exception { return photos.values(); } /** GET request handler for single photo */ @RestMethod(name=GET, path="/{id}", serializers=ImageSerializer.class, summary="Get a photo by ID") public BufferedImage getPhoto(@Path("id") String id) throws Exception { Photo p = photos.get(id); if (p == null) throw new RestException(SC_NOT_FOUND, "Photo not found"); return p.image; } /** PUT request handler */ @RestMethod(name=PUT, path="/{id}", parsers=ImageParser.class, summary="Add or overwrite a photo") public String addPhoto(@Path("id") String id, @Body BufferedImage image) throws Exception { photos.put(id, new Photo(id, image)); return "OK"; } /** POST request handler */ @RestMethod(name=POST, path="/", parsers=ImageParser.class, summary="Add a photo") public Photo setPhoto(@Body BufferedImage image) throws Exception { Photo p = new Photo(UUID.randomUUID().toString(), image); photos.put(p.id, p); return p; } /** DELETE request handler */ @RestMethod(name=DELETE, path="/{id}", summary="Delete a photo by ID") public String deletePhoto(@Path("id") String id) throws Exception { Photo p = photos.remove(id); if (p == null) throw new RestException(SC_NOT_FOUND, "Photo not found"); return "OK"; } /** Serializer for converting images to byte streams */ public static class ImageSerializer extends OutputStreamSerializer { /** * Constructor. * @param ps The property store containing all the settings for this object. */ public ImageSerializer(PropertyStore ps) { super(ps, null, "image/png", "image/jpeg"); } @Override /* Serializer */ public OutputStreamSerializerSession createSession(SerializerSessionArgs args) { return new OutputStreamSerializerSession(args) { @Override /* SerializerSession */ protected void doSerialize(SerializerPipe out, Object o) throws Exception { RenderedImage image = (RenderedImage)o; String mediaType = getProperty("mediaType", String.class, (String)null); ImageIO.write(image, mediaType.substring(mediaType.indexOf('/')+1), out.getOutputStream()); } }; } } /** Parser for converting byte streams to images */ public static class ImageParser extends InputStreamParser { /** * Constructor. * @param ps The property store containing all the settings for this object. */ public ImageParser(PropertyStore ps) { super(ps, "image/png", "image/jpeg"); } @Override /* Parser */ public InputStreamParserSession createSession(final ParserSessionArgs args) { return new InputStreamParserSession(args) { @Override /* ParserSession */ @SuppressWarnings("unchecked") protected <T> T doParse(ParserPipe pipe, ClassMeta<T> type) throws Exception { return (T)ImageIO.read(pipe.getInputStream()); } }; } } }

12.6 - SqlQueryResource

The SqlQueryResource class shows examples of the following:

The example uses embedded Derby to create a database whose name is defined in the external configuration files.

Pointing a browser to the resource shows the following:

http://localhost:10000/sqlQuery

Running a query results in the following output:

select count(*) from SYS.SYSTABLES; select TABLEID,TABLENAME,TABLETYPE from SYS.SYSTABLES;

SqlQueryResource.java

/** * Sample resource that shows how Juneau can serialize ResultSets. */ @RestResource( path="/sqlQuery", messages="nls/SqlQueryResource", title="SQL query service", description="Executes queries against the local derby '$C{SqlQueryResource/connectionUrl}' database", htmldoc=@HtmlDoc( widgets={ StyleMenuItem.class }, navlinks={ "up: request:/..", "options: servlet:/..", "$W{StyleMenuItem}", "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java" }, aside={ "<div style='min-width:200px' class='text'>", " <p>An example of a REST interface over a relational database.</p>", " <p><a class='link' href='?sql=select+*+from sys.systables'>try me</a></p>", "</div>" } ) ) public class SqlQueryResource extends BasicRestServlet { private String driver, connectionUrl; private boolean allowUpdates, allowTempUpdates, includeRowNums; /** * Initializes the registry URL and rest client. * * @param builder The resource config. * @throws Exception */ @RestHook(INIT) public void initConnection(RestContextBuilder builder) throws Exception { Config cf = builder.getConfig(); driver = cf.getString("SqlQueryResource/driver"); connectionUrl = cf.getString("SqlQueryResource/connectionUrl"); allowUpdates = cf.getBoolean("SqlQueryResource/allowUpdates", false); allowTempUpdates = cf.getBoolean("SqlQueryResource/allowTempUpdates", false); includeRowNums = cf.getBoolean("SqlQueryResource/includeRowNums", false); try { Class.forName(driver).newInstance(); } catch (Exception e) { throw new RuntimeException(e); } } /** GET request handler - Display the query entry page. */ @RestMethod(name=GET, path="/", summary="Display the query entry page") public Div doGet(RestRequest req, @Query("sql") String sql) { return div( script("text/javascript", "\n // Quick and dirty function to allow tabs in textarea." +"\n function checkTab(e) {" +"\n if (e.keyCode == 9) {" +"\n var t = e.target;" +"\n var ss = t.selectionStart, se = t.selectionEnd;" +"\n t.value = t.value.slice(0,ss).concat('\\t').concat(t.value.slice(ss,t.value.length));" +"\n e.preventDefault();" +"\n }" +"\n }" +"\n // Load results from IFrame into this document." +"\n function loadResults(b) {" +"\n var doc = b.contentDocument || b.contentWindow.document;" +"\n var data = doc.getElementById('data') || doc.getElementsByTagName('body')[0];" +"\n document.getElementById('results').innerHTML = data.innerHTML;" +"\n }" ), form("servlet:/").method(POST).target("buf").children( table( tr( th("Position (1-10000):"), td(input().name("pos").type("number").value(1)), th("Limit (1-10000):"), td(input().name("limit").type("number").value(100)), td(button("submit", "Submit"), button("reset", "Reset")) ), tr( td().colspan(5).children( textarea().name("sql").text(sql == null ? " " : sql) .style("width:100%;height:200px;font-family:Courier;font-size:9pt;").onkeydown("checkTab(event)") ) ) ) ), br(), div().id("results"), iframe().name("buf").style("display:none").onload("parent.loadResults(this)") ); } /** POST request handler - Execute the query. */ @RestMethod(name=POST, path="/") public List<Object> doPost(@Body PostInput in) throws Exception { List<Object> results = new LinkedList<Object>(); // Don't try to submit empty input. if (StringUtils.isEmpty(in.sql)) return results; if (in.pos < 1 || in.pos > 10000) throw new RestException(SC_BAD_REQUEST, "Invalid value for position. Must be between 1-10000"); if (in.limit < 1 || in.limit > 10000) throw new RestException(SC_BAD_REQUEST, "Invalid value for limit. Must be between 1-10000"); // Create a connection and statement. // If these fails, let the exception transform up as a 500 error. Connection c = DriverManager.getConnection(connectionUrl); c.setAutoCommit(false); Statement st = c.createStatement(); String sql = null; try { for (String s : in.sql.split(";")) { sql = s.trim(); if (! sql.isEmpty()) { Object o = null; if (allowUpdates || (allowTempUpdates && ! sql.matches("(?:i)commit.*"))) { if (st.execute(sql)) { ResultSet rs = st.getResultSet(); o = new ResultSetList(rs, in.pos, in.limit, includeRowNums); } else { o = st.getUpdateCount(); } } else { ResultSet rs = st.executeQuery(sql); o = new ResultSetList(rs, in.pos, in.limit, includeRowNums); } results.add(o); } } if (allowUpdates) c.commit(); else if (allowTempUpdates) c.rollback(); } catch (SQLException e) { c.rollback(); throw new RestException(SC_BAD_REQUEST, "Invalid query: {0}", sql).initCause(e); } finally { c.close(); } return results; } /** The parsed form post */ public static class PostInput { public String sql; public int pos = 1, limit = 100; } }

samples.cfg

#================================================================================ # SqlQueryResource properties #================================================================================ [SqlQueryResource] driver = org.apache.derby.jdbc.EmbeddedDriver connectionUrl = jdbc:derby:C:/testDB;create=true allowTempUpdates = true includeRowNums = true

12.7 - ConfigResource

The ConfigResource class is a predefined reusable resource.
It provides a REST interface for reading and altering the microservice config file.

Pointing a browser to the resource shows the following:

http://localhost:10000/config

An edit page is provided for altering the raw config file:

http://localhost:10000/config/edit

The Config class is a serializable POJO, which makes the resource relatively straightforward to implement.

ConfigResource.java

/** * Shows contents of the microservice configuration file. */ @RestResource( path="/config", title="Configuration", description="Contents of configuration file.", htmldoc=@HtmlDoc( navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS", "edit: servlet:/edit" } ) ) public class ConfigResource extends BasicRestServlet { @RestMethod(name=GET, path="/", description="Show contents of config file.") public ObjectMap getConfig() throws Exception { return getServletConfig().getConfig().asMap(); } @RestMethod(name=GET, path="/edit", description="Edit config file.") public Form getConfigEditForm(RestRequest req) throws Exception { return form().id("form").action("servlet:/").method("POST").enctype("application/x-www-form-urlencoded").children( div()._class("data").children( table( tr(td().style("text-align:right").children(button("submit","Submit"),button("reset","Reset"))), tr(th().child("Contents")), tr(th().child( textarea().name("contents").rows(40).cols(120).style("white-space:pre;word-wrap:normal;overflow-x:scroll;font-family:monospace;") .text(getServletConfig().getConfig().toString())) ) ) ) ); } @RestMethod(name=GET, path="/{section}", description="Show config file section.", swagger={ "parameters:[", "{name:'section',in:'path',description:'Section name.'}", "]" } ) public ObjectMap getConfigSection(@Path("section") String section) throws Exception { return getSection(section); } @RestMethod(name=GET, path="/{section}/{key}", description="Show config file entry.", swagger={ "parameters:[", "{name:'section',in:'path',description:'Section name.'},", "{name:'key',in:'path',description:'Entry name.'}", "]" } ) public String getConfigEntry(@Path("section") String section, @Path("key") String key) throws Exception { return getSection(section).getString(key); } @RestMethod(name=POST, path="/", description="Sets contents of config file from a FORM post.", swagger={ "parameters:[", "{name:'contents',in:'formData',description:'New contents in INI file format.'}", "]" } ) public Config setConfigContentsFormPost(@FormData("contents") String contents) throws Exception { return setConfigContents(new StringReader(contents)); } @RestMethod(name=PUT, path="/", description="Sets contents of config file.", swagger={ "parameters:[", "{in:'body',description:'New contents in INI file format.'}", "]" } ) public Config setConfigContents(@Body Reader contents) throws Exception { return getServletConfig().getConfig().load(contents, true).asMap(); } @RestMethod(name=PUT, path="/{section}", description="Add or overwrite a config file section.", swagger={ "parameters:[", "{name:'section',in:'path',description:'Section name.'}", "{in:'body',description:'New contents for section as a simple map with string keys and values.'}", "]" } ) public ObjectMap setConfigSection(@Path("section") String section, @Body Map<String,String> contents) throws Exception { getServletConfig().getConfig().setSection(section, contents); return getSection(section); } @RestMethod(name=PUT, path="/{section}/{key}", description="Add or overwrite a config file entry.", swagger={ "parameters:[", "{name:'section',in:'path',description:'Section name.'}", "{name:'key',in:'path',description:'Entry name.'}", "{in:'body',description:'New value as a string.'}", "]" } ) public String setConfigSection(@Path("section") String section, @Path("key") String key, @Body String value) throws Exception { getServletConfig().getConfig().put(section, key, value, false); return getSection(section).getString(key); } private ObjectMap getSection(String name) { ObjectMap m = getServletConfig().getConfig().getSectionMap(name); if (m == null) throw new RestException(SC_NOT_FOUND, "Section not found."); return m; } }

12.8 - LogsResource

The LogsResource class is a reusable predefined resource.
It provides a REST interface for the log files generated by the microservice.

Pointing a browser to the resource shows the following:

http://localhost:10000/logs

13 - Security Best-Practices

Security is always an ongoing concern in any library. If you discover any security vulnerabilities in this code, please refer to the instructions found here:

13.1 - juneau-marshall

Demarshalling vulnerabilities

One common security vulnerability is the ability to create arbitrary Java object instances through crafted user input. For example, support for constructing POJOs based on an input attribute defining a fully-qualified class name like "{class:'com.foo.MyBean',...}"

Fortunately, Juneau does not support an open-ended "class attribute. As a rule, it should not be possible to create arbitrary POJOs by any of the parsers. The demarshalled object types are inferred via reflection of the class objects passed in through the parser method (e.g. JsonParser.DEFAULT.parse(input, MyBean.class)). As long as the Class object passed into this method is not constructed from user-generated input, it should be free from demarshalling vulnerabilities.

The following example shows a potential vector that circumvents the restriction above:

// Don't do this! Class c = Class.forName(someUserInputString); JsonParser.DEFAULT.parse(input, c); // Oops! Security hole!

Juneau does support something similar to a "class" attribute that allows you to define the POJO type at runtime. This is the "type" attribute. The difference is that it's not possible to specify fully-qualified class names in "type" attributes, and instead can only specify type keys defined through bean dictionaries. Instead of serializing the fully-qualified class names in the output, we instead serialize type names that represent those POJO types.
i.e. instead of "class='com.foo.MyBean'", we instead serialize "type='MyBeanIdentifier'".
Since bean types are defined at compile time, it's impossible to instantiate arbitrary POJOs.

POJO types of generalized input are also inferred through swaps. Again, since the POJO types are hardcoded at compile time, these should not be subject to demarshalling vulnerabilities. However, it is possible to circumvent this through your swap implementation as shown below:

// Don't do this! public class MyInsecureSwap extends PojoSwap<ObjectMap,Object> { public Object swap(BeanSession session, ObjectMap input) throws Exception { // Security hole! return Class.forName(input.getString("class")).newInstance(); } }

Note that the JsoParser, a thin layer of the Juneau Parser API written on top of plain-old Java Object Serialization which itself is vulnerable to demarshalling issues. Due to this, the JSO parser is not included in any of the default REST servlet implementations. Be especially careful when using this parser, particularly if you want to use it for handing application/x-java-serialized-object input through REST servlets.

All other parsers (JSON, URL-Encoding, MessagePack, etc...) work the same way in determining POJO types, so should be safe from demarshalling vulnerabilities.

Dependent libraries

When accessing security vulnerabilities of any library, dependent libraries must also be taken into account:

  • The JSON, HTML, MsgPack, URL-Encoding, and UON parsers are written from scratch and do not rely on any other parsing technologies.
  • The XML and HTML parsers uses the built-in Java StAX parser. This *should* be free from vulnerabilities.
  • The RDF parsers rely on Apache Jena 2.7.1. As of 7.0.1, no known security vulnerabilities exist that affect Juneau at this time.

13.2 - juneau-svl

Care must be used when defining new Vars using the SVL API since mistakes could potentially expose system properties, environment variables, or even file system files.

For recap, the SVL support allows you to embed variables of the form "$X{key}" inside strings that get resolved to other strings. The resolved strings themselves can also contain variables that also get recursively resolved.

An example of a potential security hole is shown below that could potentially expose any file on a file system through a REST request:

public String doUnsafeGet(RestRequest req) { // Security hole! return req.getVarResolver().resolve("$RQ{foo}"); }

This code is simply echoing the value of the foo query parameter. Now say for example that a bad actor passes in the query string "foo=$F{/some/file/on/file/system}". The $F variable allows you to resolve the contents of files using SVL, and is provided by default using the built-in variable resolver returned by the RestRequest object. You've potentially just exposed the contents of that file through your REST interface.

In reality, the above security hole does not exist because of the following restrictions:

  • Vars have two methods Var.allowNested() and Var.allowRecurse() that can be overridden to prevent recursive processing of string variables. These are both false for the $R variable, so the $F variable in the result will never get processed and instead be treated as plain text.
  • The $F variable only allows you to retrieve files within the JVM starting directory.

Even though the built-in Juneau variables are safe, special care is needed when defining your own custom variables. If your variable resolves user input in any way, it's HIGHLY recommended that you override the Var.allowNested() and Var.allowRecurse() methods to prevent recursive handling of variables.

13.3 - juneau-rest-server

Denial of service attacks can be alleviated through the maxInput() setting. Arbitrarily-large input will trigger an exception before causing out-of-memory errors. The default value for this setting is 100MB.

Since the parsers do not use intermediate DOMs and instead parse directly into Java objects, deeply nested data structures will almost always trigger stack overflow errors long before memory consumption becomes an issue. However, this is NOT true of the RDF parsers that use an intermediate DOM. If parsing RDF, you may want to consider lowering the max-input value above.

Release Notes

Release Notes

5.0.0.0 (Jun 11, 2012)

Version 5.0 marks a major release milestone for the Juno/JJSON library. It is now available for download from iRAM under the name "Juno (previously JJSON)". The Juno Starters Guide has been updated to reflect new functionality in this release.

  • New name.
    Unfortunately, "JJSON" was already trademarked by another similar library. Therefore, it's been renamed "Juno" (after the Roman goddess and wife of Jupiter) which does not appear to have any similar trademark issues (crosses fingers). The name is also a play on the word "Uno", indicating that this is a single simple unifying interface of several kinds of technology.
  • Simplified APIs for working with beans.
    Significant improvements have been made to the parsers to make it easier to convert serialized POJOs back into their original forms.
  • Serializer/Parser classes now directly subclass from BeanContext.
    In previous releases, if you wanted to change the way beans were handled by the serializers and parsers, you had to construct a separate bean map factory and pass it to the serializer or parser. Now, you can call the bean map factory methods directly on the serializer or parser class.
  • Simplified Filter API for handling non-standard POJOs.
    The API for handling non-standard POJOs has been simplified by introducing the concept of a Transform class, which is associated with the BeanContext class (and thus the Serializer and Parser classes too) through the BeanContext.addTransforms(Class[]) method.
    Two new subclasses of Transform: This new API replaces the previous separate Cast and BeanFilter APIs which were considerably more complicated and puts them under a common API.
  • Elimination of _class attributes in parsable output.
    One of the complaints about the previous version of JJSON was that if you wanted to have the resulting JSON or XML be parsable back into beans, you had to enable the "addClassAttrs" property on the bean map factory class so that "_class" attributes could be added to the output.
    This requirement is virtually eliminated in v5. In many cases, the parsers are able to determine through reflection what the correct target type is based on the top-level class passed in on the parse method.
  • Performance improvements.
    Several significant performance improvements have been made in this release.
    • New Reader-based JSON parser.
      Previously, the JSON parser required that the entire JSON text be loaded into memory as a String before being parsed. The new JSON parser is Reader-based which significantly reduces memory consumption.
    • New StAX-based XML parser.
      The old XML parser was based on DOM. The new XML parser uses a StAX parser which significantly reduces memory consumption.
    • Caching of reflection data in the BeanMap API.
      The number of reflection calls have been significantly reduced in the BeanMap API code. Reflection is used to determine the class types of property values on beans. This information is now cached and persisted so that the reflection API calls to determine class types are only performed the first time a bean type is encountered.
    • Automatic support for GZIP compression/decompression in RestServlets.
      This is completely transparent to the developer. The output writer is negotiated by the framework to automatically handle compression and charset requests without the developer needing to know anything about it.
  • Cognos/XML support.
  • JSON-schema support.
  • New PojoIntrospector class.
  • Significant REST servlet API improvements.
    • Defining child resources is considerably simpler now. In addition to the standard doX() methods for handling the requests for the current resource, you can also define getX() methods for returning child resources which automatically become available under the child URL specified by the getter name.
    • Initialization of the child resources occurs automatically when the parent resource initialization occurs.
    • Other improvments have been made in the area of automatic negotiation of input and output type streams. For example, automatic support is provided for GZIP (Accept-Encoding: gzip) and charsets (e.g Accept-Charset: SJIS) on both incoming and outgoing data. It's all transparent from a developers perspective. The developer simply working with POJOs, and all details about content types, encoding, charsets, and so forth are handled by the framework.
    • Support for generating complex OPTIONS pages for resources.
  • Automatic support for SOAP XML output on "text/soap+xml" requests against RestServlet.
  • Support for XML namespaces.
  • Support for setting the XML root element name by either passing in a parameter on the serializer, or by specifying it via a @Bean annotation.
  • Support for loading beans directly from Readers and Strings.
  • Parsing support for POJOs of type Enum.
  • Significant improved support for various flavors of parameterized types, such as subclasses of parameterized types (e.g. MyBeanList extends LinkedList<MyBean>).
  • Improved ordering of bean properties (should now be ordered as they are defined in the class).
  • Various default filters provided:
    • byte[]<-->Base64 encoded strings
    • Date/Calendar<-->ISO8601/RFC822/Long
  • New HtmlParser and UrlEncodingParser classes.
  • HtmlSerializer now produces XHTML.

5.0.0.1 (Jun 14, 2012)

Juno 5.0.0.1 is a moderate update.

  • New support for generating XML-Schema documents from POJO models.
  • New support for serializing to RDF/XML.

5.0.0.2 (Sept 28, 2012)

Juno 5.0.0.2 is a minor update.

  • Improvements to Javadocs. Most of the information in the Juno Starters Guide wiki has been moved into the overview and package-level javadocs.
    Since the information is now written in HTML, you can now copy and paste the code examples directly from the Javadocs.
    The code examples are also syntax-highlighted using CSS.
  • Support for defining default XML namespaces on packages and classes for the XML and RDF serializers.
  • Restructured the packages along content type support (e.g. all JSON support moved to org.apache.juneau.json).
  • Automatic support for parsing maps with Enum keys, and parsing Enum strings.
    This was previously possible using filters, but now it's built-in for all the parsers.
  • Replaced the ObjectList.toXArray() methods with a new elements(Class<T> type) method that's more efficient and avoids creating an unnecessary array.
  • Support for parsing into beans with read-only properties.
    New @BeanConstructor annotation allows you to specify bean property values to be passed in through a constructor.
  • Separated the rest library into separate independent client and server libraries.
    Use one, use both, it's up to you.

5.0.0.3 (Oct 3, 2012)

Juno 5.0.0.3 is a minor update.

  • Support for parsing into read-only beans (i.e. beans with only getters, property values set through constructor args).
    To support this, the @BeanConstructor annotation has been added.
  • Merged separate settings classes back into their base classes (simplifies the API).
  • SerializerGroups and ParserGroups now share BeanContexts to reduce memory consumption of class type metadata.

5.0.0.4 (Oct 7, 2012)

Juno 5.0.0.4 is a minor update.

  • New @RestMethod annoation on RestServlet methods.
    Allows the usage of URL pattern matching and automatic conversion of URL variables to arguments passed to method handlers.
    See RestServlet for more information.
  • Enhancements to BeanContext.convertToType(Object,Class) to be able to convert Strings to classes with fromString(String)/valueOf(String) static methods or T(String) constructors.

5.0.0.5 (Oct 29, 2012)

Juno 5.0.0.5 is a major update.

  • New @RestChild annotation for identifying child resources.
  • New traversable and filterable attributes added to @RestMethod annotation.
    Eliminates the need for PojoResource and FilteredRestResource classes.
  • Simplified client API. Easier to use when making multiple connections to the same server.
  • Support for pluggable authentication in the client API.
  • Support for authenticating against Jazz Team Servers.
  • Support for rendering package-level Javadocs in REST resources.
  • Support for parsing of header values into specific object types.
  • Changed default XML representation to not include JSON-type attributes. Produces cleaner XML.
  • New resourceUri attributed added to @Bean annotation to associate beans with resource URIs.
    • Used for automatically creating hyperlinks in HtmlSerializer.
    • Used for automatically creating uri attributes in XmlSerializer.
    • Used for automatically creating rdf:about attributes in RdfXmlSerializer.

5.0.0.6 (Oct 30, 2012)

Juno 5.0.0.6 is a minor update that fixes a small bug in 5.0.0.5.

5.0.0.7 (Jan 20, 2013)

Juno 5.0.0.7 is a major update.

Core API updates
  • Combined previous 3 libraries into a single library.
  • New ParserListener class.
    Adds ability to find and process unknown bean properties during parsing.
  • Enhancements to XmlParser:
    • Coalescing support
    • Validations support
    • Support for replacing entity references
    • Resolver support
    • Event allocator support
    • Trim-whitespace support
  • Enhanced XML support:
    • New @Xml.format annotation.
      Controls how POJOs get serialized to XML.
      Also allows you to collapse collections and arrays.
    • New @Xml.namespaces annotation.
      Namespaces can be defined at package, class, method, or field levels.
    • New @Xml.nsUri annotation.
      Shortcut for specifying namespace URIs.
    • New @Xml.valAttr annotation.
      Serializes a bean property value as an attribute.
    • Ability to override XS and XSI namespaces on XML and RDF/XML serializers.
    • Ability to override RDF namespace on RDF/XML serializer.
    • New more-efficient namespace resolution.
  • New configurable property classes for everything are now structured better and easier to locate and identify through the following new classes:
  • Enhancements to BeanContext:
    • Ability to mark bean properties as hidden using @BeanProperty(hidden) so that they don't get serialized.
    • Simplified ClassType ClassMeta API.
      Combined 4 classes into a single class.
    • New @Bean.filter and @BeanProperty.filter annotations.
      Used for defining filters on bean classes and bean properties instead of just globally through BeanContext.addTransforms(Class[]).
    • New PropertyNamer API / @Bean.propertyNamer annotation.
      Used for customizing bean property names.
    • New @BeanProperty.beanUri and @BeanProperty.id annotations.
      Used for associating beans with URLs and IDs.
      Used by XML serializer to add a url attribute on a bean element.
      Used by RDF/XML serializer to construct rdf:resource attributes.
    • New @BeanProperty(properties) annotation. Used for limiting properties on child elements.
  • Automatic support for URL and URI objects.
    • Converted to hrefs in HTML.
    • Converted to url attributes in XML.
    • Converted to resource:about attributes in RDF/XML.
  • Improvements to Javadocs.
  • Improved PojoQuery support.
REST client updates
  • GZIP compression support.
  • Bug fixes.
REST server updates
  • Support for overriding bean context and serializer properties in a REST method call through new RestResponse.setProperty(String,Object) method.
    For example, allows you to control whitespace options on a per-request basis.
  • Several new annotations on REST servlets:
    • @RestResource(filters) - Associate post-formatting filters on a resource level.
    • @RestResource.guards - Associate resource-level guards.
    • @RestResource.messages - Associate a resource bundle with a REST servlet. Comes with several convenience methods for looking up messages for the client locale.
    • @RestResource.properties - Override default bean context, serializer, and parser properties though an annotation.
  • Several new annotations on REST methods:
    • @RestMethod(filters) - Associate post-formatting filters on a method level.
    • @RestMethod(guards) - Associate method-level guards.
  • New annotations on REST method parameters with automatic conversion:
    • @Attr - A parameter or URL variable value as a parsed POJO.
    • @Param - A query parameter value as a parsed POJO.
    • @PathRemainder- The remainder after a URL pattern match as a String.
    • @Header - An HTTP header value as a parsed POJO.
    • @Content - The HTTP content as a parsed POJO.
    • @Method - The HTTP method name as a String.
  • HTTP response content POJOs can now simply be returned from methods instead of calling RestResponse.setOutput(Object).

5.0.0.8 (Jan 30, 2013)

Juno 5.0.0.8 is a minor update.

  • New INI file support.
    • Makes reading, updating, and manipulating INI configuration files a snap.
    • Supports automatic conversion of data types in line with the functionality of the rest of the product.
    • Comments and layout of INI files are persisted during saves.

5.0.0.9 (Feb 26, 2013)

Juno 5.0.0.9 is a moderate update.

Core API changes
  • INI config file support:
    • A convenient API for reading, writing, and manipulating INI files.
    • Ability to convert INI files to batch and shell environment variables.
    • Command-line interface for updating INI files.
    • Support for encoded INI file values.
  • Support for fluent-style bean setters (setters that return the bean itself).
  • Ability to use @Bean annotation to override bean identification settings.
  • New ObjectMap.cast(Class) method to convert ObjectMaps directly to beans.
REST server API changes
Other notes
  • Smaller library size (460kB).

5.0.0.10 (Mar 7, 2013)

Juno 5.0.0.10 is a minor update.

Core API changes
  • New ObjectMap.findKeyIgnoreCase(String) method.
  • HtmlSerializer will now create 2-dimensional tables for collections of mixed beans/maps if all object have the same set of property names/keys.
REST server API changes
  • New RestServletProperties class that defines all the class-level properties that can be set on the servlet.
  • Properties can be set through @RestResource.properties annotation, or new RestServlet.setProperty(String,Object) method.
  • New "?noTrace" URL parameter to prevent stack traces from being logged (for JUnit testing of error conditions).
  • New RestServletProperties.REST_useStackTraceHashes property to prevent the same stack trace from being logged multiple times.
  • New RestServletProperties.REST_renderResponseStackTraces property for preventing stack traces in responses for security reasons.
  • New overridable RestServlet.onError(HttpServletRequest,HttpServletResponse,RestException,boolean) and RestServlet.onSuccess(RestRequest,RestResponse,long) methods for plugging in your own logging and peformance monitoring.
  • Eliminated RestServlet.getInitParams() method, since it's now redundant with RestServlet.getProperties().
  • Header parameters passed as URL parameters are now case-insensitive.

5.0.0.11 (Mar 8, 2013)

Juno 5.0.0.11 is a moderate update.

REST server API changes
  • New UrlEncodingRestSerializer and UrlEncodingRestParser classes.
    Allows parsing form posts directly to POJOs.
  • Support for Accept and Content-Type "application/x-www-form-urlencoded" added by default on BasicRestServlet.
  • New RestServlet.renderError(HttpServletRequest,HttpServletResponse,RestException) method to allow customized handling of response errors.

5.0.0.12 (Mar 10, 2013)

Juno 5.0.0.12 is a minor update.

Core API changes
  • Relaxed method naming conventions when using @BeanProperty annotation.
    Methods with zero parameters are interpreted as getters, and methods with one parameter are interpreted as setters.
    Eliminated the BeanProperty.method annotation, since it's now unnecessary.
REST server API changes
  • Significantly improved response error messages.
    Older messages were rather cryptic. Error conditions should be much easier to debug now.
  • New PlainTextRestSerializer class for serializing "plain/text" requests.
    Useful for debugging purposes.
  • Readers and InputStreams can now be passed in as @Content parameters if you need direct access to the HTTP body content without involving the parsers.
    Equivalent to previously calling RestRequest.getInputStream() and RestRequest.getReader().
  • Improved support for the ?debug parameter.
    Dumps better information to the log file, such as all header parameters.

5.0.0.13 (Mar 14, 2013)

Juno 5.0.0.13 is a minor update.

Core API changes
  • New support for relative URIs.
    • URIs of the form "foo/bar" are interpreted as relative to the context root of the web application.
    • URIs of the form "/foo/bar" are interpreted as relative to the HTTP authority (e.g. "http://myhost:9080").
  • New SerializerContext.SERIALIZER_uriContext and SerializerContext.SERIALIZER_uriAuthority serializer properties for specifying values for relative URIs.
  • New @URI annotation that allows you to specify classes and bean properties as URLs that aren't java.net.URI or java.net.URL.
  • New HtmlSerializer.HTML_uriAnchorText HTML serializer property for tailoring how anchor text is rendered.
  • Renamed BeanProperty#uri annotation to BeanProperty#beanUri to make it clear that this property represents the URI of the bean itself instead of an arbitrary property containing a URI.
  • Removed BeanProperty#id annotation.
REST server API changes
  • Improvements to RestServlet to automatically handle relative URIs in POJOs.
    • SerializerContext.SERIALIZER_uriContext property set by default to web app context root.
    • SerializerContext.SERIALIZER_uriAuthority property set by default to the request scheme+hostname+port.
  • Fixed bug involving Accept-Charset header in Chrome that prevented HTML output from rendering correctly in that browser.
    Accept-Charset handling should now be fully W3C compliant.

5.0.0.14 (Mar 23, 2013)

Juno 5.0.0.14 is a major update.

The biggest change is that the RestSerializer, RestParser, RestSerializerGroup, and RestParserGroup classes have been eliminated entirely.
Instead, the existing Serializer, Parser, SerializerGroup, and ParserGroup classes of the core API have been augmented to replace them.

Adoptions will be required if you have previously used these classes.

Core API changes
  • New org.apache.juneau.serializer package.
    • Entirely reworked class hierarchy to make it easier to define new serializers.
    • New WriterSerializer base class for defining character-based serializers.
    • New OutputStreamSerializer base class for defining byte-based serializers.
    • Updated SerializerGroup class with full support for RFC2616 Accept-Content headers.
    • Improved cloning support on serializers and serializer groups.
  • New org.apache.juneau.parser package.
    • Entirely reworked class hierarchy to make it easier to define new parsers.
    • New ReaderParser base class for defining character-based parsers.
    • New InputStreamParser base class for defining byte-based parsers.
    • Improved cloning support on parsers and parser groups.
  • New org.apache.juneau.transform package.
    • Cleaner class structure.
    • Improved BeanFilter class for defining property filters on beans.
    • Improved PojoQuery class for defining filters on objects (previously called ObjectFilter).
  • New org.apache.juneau.encoders package.
    • Defines API for Encoders for enabling compression in REST servlets and clients.
    • Previously, gzip compression was enabled by default. This new API allows you to plug in your own compression algorithms.
    • New GzipEncoder class for enabling gzip compression.
    • New EncoderGroup class for managing multiple encoders and finding them based on RFC2616 Accept-Encoding header values.
  • New org.apache.juneau.plaintext package.
  • New org.apache.juneau.jso package.
    • New JsoSerializer class for serializing application/x-java-serialized-object content.
  • New org.apache.juneau.soap package.
  • Improved cloning support on the BeanContext class.
    • Better caching. Improved caching performance.
  • JsonMap and JsonList changed to ObjectMap and ObjectList to better reflect that they're not limited to just JSON support.
  • Renamed PojoSwap to PojoQuery to not confuse it with the new Filter API.
REST server API changes
  • Eliminated org.apache.juneau.rest.serializers and org.apache.juneau.rest.parsers packages.
    • All existing REST serializers and parsers merged into the core API.
REST client API changes
  • Simplified RestClient API.
    • You can now only specify a single serializer or parser per client. This significantly simplifies the code.
    • Support for Encoders.
  • Eliminated RestCmdLine (since it's essentially redundant with CURL).

5.0.0.15 (Mar 24, 2013)

Juno 5.0.0.15 is a moderate update.

  • Juno-Wink integration components that have been requested by many for a long time!
    Refer to org.apache.juneau.rest.jaxrs for information.
  • New @Produces annotation in place of ISerializer.getMediaTypes() for specifying what media types a serializer produces.
    Available when subclassing from Serializer.
  • New @Consumes annotation in place of IParser.getMediaTypes() for specifying what media types a parser consumes.
    Available when subclassing from Parser.

5.0.0.16 (Mar 25, 2013)

Juno 5.0.0.16 is a minor update.

  • New @Properties REST method parameter annotation that can be used to get the runtime properties map through a parameter instead of through RestResponse.

5.0.0.17 (Mar 25, 2013)

Juno 5.0.0.17 is a minor update.

  • Charset now passed as a parameter to IOutputStreamSerializer.serialize() and IInputStreamParser.parse().

5.0.0.18 (Mar 27, 2013)

Juno 5.0.0.18 is a moderate update.

The biggest change is the introduction of the RdfSerializer class that uses Jena to generate RDF/XML, RDF/XML-ABBREV, N-Tuple, N3, and Turtle output.

This code should be considered prototype-quality, and subject to change in the future.
There are plans of adding an equivalent RdfParser class in the future, so the serializer logic may need to be tweaked to allow POJOs to be reconstituted correctly in the parser.

The RdfXmlSerializer class should be considered deprecated for now.
However, I'm keeping it around, since it's considerably faster and uses far less memory than the Jena-based serializer since it serializes directly from POJOs to RDF/XML.
It may or may not be removed in the future depending on demand.

Other changes

5.0.0.19 (Apr 1, 2013)

Juno 5.0.0.19 is a minor update.

  • New methods on RestServlet:
    • RestServlet.onPreCall(RestRequest)
    • RestServlet.onPostCall(RestRequest,RestResponse)
  • TRIM_NULLS setting changed to SerializerContext.SERIALIZER_trimNullProperties.
    New property default is true. Only applies to bean properties, not map or collection entries.

5.0.0.20 (Apr 7, 2013)

Juno 5.0.0.20 is a major update.

Core API changes
  • New Jena-based RdfSerializer for serializing POJOs to RDF/XML, RDF/XML-ABBREV, N-Triple, Turtle, and N3.
    Serializes ANY POJOs to RDF, even simple objects and primitives.
  • New Jena-based RdfParser for parsing RDF/XML, RDF/XML-ABBREV, N3, Turtle, and N-Triple back into POJOs.
  • XmlSerializerContext.XML_autoDetectNamespaces default changed to true.
    The old default value would cause XML with unmapped namespaces if you didn't manually specify them via the XmlSerializerContext.XML_namespaces annotation.
    While setting the default to true is somewhat slower (since the serializer must crawl the POJO tree to find namespaces), the benefits of having it work out-of-the-box outweighs the performance concerns.
    For developers concerned about performance, they can always change it back to false and specify the namespaces themselves.
REST server API changes
  • Allow inheritance of @RestResource annotation.
    Serializers, parsers, filters, properties , guards, and converters definitions are automatically inherited from parent classes and interfaces.
  • Enhancements to @RestMethod annotation:
    • New RestMethod.filters() annotation for defining POJO filters at the method level.
    • New RestMethod.serializersInherit() and RestMethod.parsersInherit() annotations for controlling how serializers and parsers (and associated filters and properties) are inherited from the class.
      This replaces the previous addSerializers and addParsers annotations.
  • New RestServletJenaDefault servlet that includes serialization/parsing support for all Jena-based serializers and parsers.
  • New DefaultJenaProvider JAX-RS provider that includes serialization/parsing support for all Jena-based serializers and parsers.
  • Eliminated RestServletChild class.
    It's redundant with the introduction of inheritable annotations.
  • New methods on RestServlet:
    • RestServlet.createConfigFactory()
    • RestServlet.createSerializers()
    • RestServlet.createParsers()
    These augment the existing getBeanContext() / getSerializers() / getParsers() methods.
REST client API changes
  • New RestCall.setDateHeader(String,Object) method for setting ISO8601 datetime headers.

5.0.0.21 (Apr 9, 2013)

Juno 5.0.0.21 is a minor update.

Core API changes
  • New HtmlDocSerializerContext.HTMLDOC_navlinks annotation for addint links to HTML page views.
  • Renamed the properties in HtmlDocSerializerContext for clarity.
Servlet API changes
  • Added new RestServlet.addDefaultProperties(ObjectMap,RestRequest) method for programatically adding properties to the property map per request.
  • Added the following new properties in the properties map to make them easily available to serializers and parsers (since they don't have access to the HTTP request object).
    Note that the SerializerContext.SERIALIZER_uriAuthority and SerializerContext.SERIALIZER_uriContext properties were previously available.
    • RestServletProperties.REST_servletPath
    • RestServletProperties.REST_pathInfo
    • RestServletProperties.REST_method
  • Path variables annotated with @Attr are now automatically URL-decoded.

5.0.0.22 (Apr 12, 2013)

Juno 5.0.0.22 is a minor update.

Core API changes
  • New @Property.nls() annotation for specifying localized property values.
    For example, allows you to set the HTMLDOC_title and HTMLDOC_description properties to localized values pulled from a resource bundle.
    See the AddressBookResource class for an example.
REST Servlet API changes
  • Fix a bug where the &Content query parameter was not always parsed correctly.

5.0.0.23 (Apr 14, 2013)

Juno 5.0.0.23 is a minor update.

  • Simplified Cognos support.
  • Fixed bug where @Xml annotation was not being inherited by inner classes.
  • Javadoc stylesheet improvements.

5.0.0.24 (May 9, 2013)

Juno 5.0.0.24 is a major update.

Core API updates
  • New support for ATOM.
    • New AtomFeedResource class added to sample war.
  • New XmlFormat.CONTENT enum value.
    Allows bean properties to be persisted as XML element text.
  • New XmlContentHandler class and @Xml.contentHandler annotation.
    Allows customized serialization and parsing of beans to XML element text.
    Added for support of ATOM text content that must support both plain text and embedded XHTML.
  • New @XmlSchema and updated @XmlNs annotations to better mimic JAXB.
  • Removed @Xml.valAttr annotation since it's now redundant with @Xml(format=CONTENT).
  • Fixed timezone bug in CalendarSwap.
  • Simplified Serializer.serialize(Object,Object,SerializerContext) method.
  • Fixed bug where lists returned by ObjectMap.getObjectList(String) were not updatable.
  • Eliminated old RDF/XML serializer.
Documentation updates

5.0.0.25 (May 11, 2013)

Juno 5.0.0.25 is a minor update.

Core API updates
  • New ResultSetList DTO for serializing SQL result sets to JSON/XML/HTML and so forth.
  • New SqlQueryResource class in the sample war for demonstrating the ResultSetList DTO.
Server API updates
  • Fixed issue with media type for CSS files being reported as "text/plain" instead of "text/css".
  • Moved initialization of class properties to before the call to Servlet.init() so that getProperties() can be called during servlet initialization.
  • New @Property.type annotation with support for using system properties as resource properties.

5.0.0.26 (Jun 5, 2013)

Juno 5.0.0.26 is a minor update.

  • FindBug fixes.
  • Changed the way child REST resources are defined.
    Eliminated the @RestChild annotation on getter methods and replaced it with @RestResource(children) defined on the resource class itself.
    Child resource paths are specified through @RestResource(path).
  • New ChildResourceDescriptions bean for automatically generating the contents of router resource pages.
  • Changed @RestMethod.pattern() to @RestMethod(path) for naming consistency.

5.0.0.27 (July 7, 2013)

Juno 5.0.0.27 is a moderate update.

5.0.0.28 (July 9, 2013)

Juno 5.0.0.28 is a moderate update.

  • Fixes an OutOfMemoryError and performance issue caused by incorrect caching of class metadata.
  • Added WriterSerializer.serialize(Object,Writer) convenience method for serializing directly to a writer.
    Applies to all serializers.

5.0.0.29 (Aug 2, 2013)

Juno 5.0.0.29 is a moderate update.

  • Revamped the API for filter support:
    • Updated BeanFilter class to mirror the @Bean annotation.
    • Introduced support for bean Bean.subTypeProperty() subtypes.
    • Replaced @Bean(filter=xxx) with new @Transform annotation.
  • Revamped URL-Encoding support.
    The old URL-Encoding serializer and parser simply used the JSON serializer/parser with a thin URL-encoding top layer.
    The new URL-Encoding serialize and parser was written from scratch and is considerably more consistent in design and output.
  • Improved number parsing.
    The new number parser should handle any valid numeric syntax for decimals and floats that Java itself supports.
  • JsonSerializer LAX mode now quotes reserved word attributes.
  • New predefined DateFilters with millisecond precision:
    • org.apache.juneau.transforms.DateSwap.ISO8601DTP
    • org.apache.juneau.transforms.DateSwap.ISO8601DTZP

5.0.0.30 (Aug 8, 2013)

Juno 5.0.0.30 is a minor update.

  • Fixed bug involving beans using Bean.subTypes() annotation in addition to subTypes property.
  • Modified the JSON parser to handle non-existent JSON values to get around an issue where Cognos was generating invalid JSON.

5.0.0.31 (Aug 9, 2013)

Juno 5.0.0.31 is a moderate update.

  • Simplified the Serializer and Parser class hierarchies.
    This reverses a previous change that added a bunch of interfaces in these APIs (and subsequently required compiling with Java 7 to get around a compiler bug).
    The new class hierarchy is much simpler to understand.
  • Added XMLGregorianCalendarSwap to convert these to ISO8601 strings during serialization, and vice versa during parsing.
  • Added a strict mode to JsonParser.
  • Added default JsonParser.DEFAULT_STRICT parser.

5.0.0.32 (Oct 5, 2013)

Juno 5.0.0.32 is a moderate update.

  • New support for generating and consuming fully-compliant JSON-Schema documents.
    See org.apache.juneau.dto.jsonschema for information.
  • New methods added to Parser:
    • org.apache.juneau.parser.Parser.parseMap(Object,int,Class,Class,Class)
    • org.apache.juneau.parser.Parser.parseCollection(Object,int,Class,Class)
  • @Bean annotation can now be defined on interfaces and inherited by subclasses.
  • Support for customizing serialized values for Enums through overriding toString() and fromString() on the enum class.
    Previously used Enum.valueOf() to convert strings back into Enums.
    Used for JSON-Schema support to allow JsonType enum to be serialized to lowercase per the specification (e.g. "string" instead of "STRING").
  • Cognos DTOs now have fluent-style bean setters.
  • Support for generic bean objects whose type was erased at compile time.
    Previous behavior gave you an error message that the type could not be determined.
    New behavior assumes a type of Object when the type is erased.
  • Bug fixes:
    • When duplicate fluent-style setters were defined with different parameter types (e.g. setFoo(Foo f), setFoo(Bar b)), the BeanMap API would sometime choose the wrong setter as the bean property setter.
      Now validates that the setter being chosen is the one whose return type matches the property getter.
    • Passing in Accept GET parameters with '+' (e.g. &Accept=text/json+simple) wasn't working anymore.
      The Accept parameter is supposed to interpret spaces as '+' to allow you to not have to write &Accept=text/json%2Bsimple.
    • Parsers would not set bean properties of abstract type Number.
      Now it detects the numeric type based on input and sets the value accordingly.

5.0.0.33 (Oct 20, 2013)

Juno 5.0.0.33 is a moderate update.

  • Removed generic parameter from WriterSerializer class.
    • Many of the examples in the documentation were written as follows, which resulted in "unchecked" compile warnings:
      WriterSerializer s = new JsonSerializer();
      These compile warnings will now go away.
  • New settings in BeanContext. These can be applied to all serializers/parsers.
  • Eliminated addNotBeanClassPatterns(String...) methods throughout API since these are now controlled by BeanContext.BEAN_notBeanPackages_add / BeanContext.BEAN_notBeanPackages_remove properties.
  • New settings in RestServletProperties.
    • RestServletProperties.REST_trimTrailingUriSlashes
      Also removed RestRequest.getRequestURI(boolean trimTrailingSlashes) method which is now redundant with this property.
    • RestServletProperties.REST_pathInfoBlankForNull
      Also removed RestRequest.getPathInfo(boolean returnBlankForNull) method which is now redundant with this property.
  • New JSON-Schema JsonSchemaMap class for supporting linked schemas.
  • Serializers will no longer throw an exception when maxDepth setting is reached, and will instead simply ignore content below the specified depth.
    While the old behavior was as-designed, the new behavior is more in-line with expected behavior.
  • Added support for HTTP header "X-Response-Headers" to RestServlet.
    Allows you to specify one or more headers that should be returned on the response from the servlet.
    For example, to get a page to automatically refresh every 1 second, you can append the following to a URL: ?x-response-headers={Refresh=1}
  • Removed HtmlDocSerializerContext.HTML_REFRESH setting that added a Refresh meta tag to HTML documents, since this can now be controlled through X-Response-Headers.
  • Small improvements to samples.
    • PhotosResource now includes a default entry.

5.0.0.34 (Nov 10, 2013)

Juno 5.0.0.34 is a moderate update.

  • New support for runtime-replaced variables in REST resource properties:

    @RestResource( messages="nls/Messages", properties={ @Property(name="label",value="$L{servletTitle}"), // Localized variable in Messages.properties @Property(name="javaVendor",value="$S{java.vendor}"), // System property @Property(name="foo",value="bar"), @Property(name="bar",value="baz"), @Property(name="v1",value="$R{foo}"), // Request variable. value="bar" @Property(name="v2",value="$R{$R{foo}}") // Nested request variable. value="baz" } )

    See RestServlet.createRequestVarResolver(RestRequest) for more information.
  • Eliminated @Property.type annotation which was the old way of specifying NLS variables that got resolved at runtime.
  • New methods on RestRequest:
    • RestRequest.getVarResolver()
    • RestRequest.getServletURI()
    • RestRequest.getRequestParentURI()
  • New methods on RestResponse:
    • RestResponse.sendRedirect(CharSequence)
  • New methods on RestServlet that allow easier customization by subclasses:
    • RestServlet.createConfigFactory()
    • RestServlet.createConverters()
    • RestServlet.createDefaultRequestHeaders()
    • RestServlet.createDefaultResponseHeaders()
    • RestServlet.createEncoders()
    • RestServlet.createFilters()
    • RestServlet.createGuards()
    • RestServlet.createMimetypesFileTypeMap()
    • RestServlet.createParsers()
    • RestServlet.createProperties()
    • RestServlet.createRequestProperties(ObjectMap,RestRequest)
    • RestServlet.createRequestVarResolver(RestRequest)
    • RestServlet.createSerializers()
    • RestServlet.createUrlEncodingParser()
  • Changed RestServletNls to use ResourceDescription/MethodDescription instead of RestResource/RestMethod
  • New property RestServletProperties.REST_htDocsFolder.
    New support for serving up static documents from classpath through REST interface.
  • Exception APIs now use MessageFormat (e.g. "{0}") for message variables instead of "%s".
  • New @Bean.stopClass annotation for specifying stop classes for bean properties.
  • New BeanFilter.setStopClass(Class) which is the program equivalent to the annotation above.
  • New methods on ResultSetList:
    • ResultSetList.handleBlob(Blob)
    • ResultSetList.handleClob(Clob)

5.0.0.35 (Nov 26, 2013)

Juno 5.0.0.35 is a minor update.

  • RestGuard.guard(RestRequest,RestResponse) now returns a boolean to allow redirects to login pages.
  • Fixed bug in RestServlet where occasional false positive "duplicate method with same name and path" errors were occurring.

5.0.0.36 (Dec 18, 2013)

Juno 5.0.0.36 is a minor update.

  • Implemented org.apache.juneau.urlencoding.UrlEncodingParser.parseArgs(Reader,int,ClassMeta[]).
  • name parameter of ResourceDescription#ResourceDescription(String,String,String). is now automatically URL-encoded so that the name can contain special characters (e.g. "foo/bar(baz)").
  • Support for URL-matching and path info containing encoded characters (e.g. '/') now supported.
  • Removed some lazy-initialization of bean information in ClassMeta that allowed the removal of some synchronized blocks.
  • Improved support of BeanContext.getClassMetaFromString(String). Now supports primitive arrays such as "long[]" in addition to the previous support for the equivalent "[J".
  • Various new convenience methods added to StringUtils and ClassUtils.

5.1.0.0 (Jan 18, 2014)

Juno 5.1.0.0 is a major update.

Major changes
  • Brand new REST client API that uses Apache HttpClient for HTTP communication.
    The new client API is simply a thin layer on top of HttpClient that performs serialization and parsing using Juno parsers, but leaves all the details of the HTTP connection to the Apache code.
    See the org.apache.juneau.rest.client package for details.
  • New org.apache.juneau.rest.client.jazz package and org.apache.juneau.rest.client.jazz.JazzRestClient class for performing REST operations against Jazz servers.
    Includes improved support for FORM authentication, and better SSL certificate validation.
  • Completely redesigned URL-Encoding support.
    See org.apache.juneau.urlencoding package for details.
  • Changes to Parser API.
    • Removal of ExtendedReaderParser abstract class and moved methods into ReaderParser class.
    • Removal of DataFormat class from API since it was no longer necessary due to API change above.
    • Removal of ParserStringReader class.
      This was a reader optimized to work with String input.
      However, it could interfere with garbage collection of the original string object.
      Instead, the existing ParserReader was enhanced to work well with String input, and tests show no significant performance differences.
    • New org.apache.juneau.parser.Parser.parse(Object,int,ClassMeta) convenience method added.
Other changes
  • Various new methods added to StringUtils and ClassUtils.
  • Improved support on BeanContext.getClassMetaFromString(String).
    Now supports resolving "long[]", and so forth.
  • ResourceDescription name parameter is now automatically URL-encoded in links.
  • RestRequest now correctly handles cases involving URL-encoded characters in the path info portion of URLs (e.g. http://host/contextRoot/foo%2Fbar).
  • Removed lazy-initialization that required locking in ClassMeta.
  • New BeanContext.setDefaultParser(ReaderParser) method added for specifying a default parser to use in a bean context (used when converting beans to Strings using BeanContext.convertToType(Object,Class). Old behavior simply used the default JSON serializer in these cases.
  • More consistent handling of exceptions across all parsers.
  • Minor changes to RestRequest class.
    • Changed the order of parameters on RestRequest#getParameter(String,Class).
    • Added RestRequest.getMapParameter(String,Class,Class,Class) and RestRequest.getCollectionParameter(String,Class,Class)} methods.

5.1.0.1 (Jan 25, 2014)

Juno 5.1.0.1 is a minor update.

  • Addressed some behavioral differences between Tomcat and WAS.
    • Query parameter lookup is now always case-insensitive (per WAS behavior).
    • Consistent handling of redirect requests (Tomcat and WAS handle relative redirect paths differently).
  • Fixed bug involving incorrect resolution of overlapping URL match patterns.
  • Overall improvements in HTTP request parameter and header value resolution.
  • Made workspace changes so as not to be dependent on the WAS test environment being loaded.
  • Renamed @Remainder annotation to @PathRemainder.
  • Fixed bug involving incorrect calculation of pathInfo on child resources.

5.1.0.2 (Apr 27, 2014)

Juno 5.1.0.2 is a minor update.

  • Fixed issue preventing &Accept-Language from being used as a GET parameter.
  • Minor XSS vulnerability fix.
  • Empty results on HTML pages now shows "no results" instead of a blank page.
  • Fixed issues preventing REST pages from rendering HTML in newer versions of Internet Explorer.
  • Changed RestServletProperties.REST_allowMethodParam to be disabled by default.

5.1.0.3 (Jun 28, 2014)

Juno 5.1.0.3 is a moderate update.

Core API updates
  • Ability to detect and use non-public bean classes, getters/setters, and fields using the following new properties: Removed BeanContext.INCLUDE_BEAN_FIELD_PROPERTIES and BeanContext.INCLUDE_BEAN_METHOD_PROPERTIES properties, since ignoring fields and methods can be accomplished by setting the appropriate properties above to NONE. Also, the @BeanProperty annotation can now be used on non-public fields/getters/setters to override the default behavior defined by the VISIBILITY properties identified above. This is a convenient way of identifying protected or private fields or methods as bean properties. Previously, you could only identify public fields/getters/setters using this annotation.
  • New BeanContext.BEAN_useJavaBeanIntrospector property that lets Juno use the Java bean Introspector class to determine bean properties. In the previous release, the method for determining bean properties was a mixture of Juno-based and Introspector-based. Now it's either pure Juno-based or pure Introspector-based. The result is considerably cleaner code and consistent behavior.
  • New @BeanIgnore annotation. Replaces the previous @BeanProperty(hidden=true) annotation for ignoring bean properties. Can also be used on classes that look like beans so that they're not treated as beans.
  • Support for parsing into non-static member classes. This applies to all parsers.
  • New @Json(wrapperAttr) annotation that automatically wraps beans and objects in a wrapper attribute when serializing to or parsing from JSON.
  • Changed the default ordering of bean properties to be in parent-to-child class order.
  • New readProperty() and writeProperty() methods added to BeanFilter class to allow individualized serialization and parsing behavior on a class-by-class basis.
  • Eliminated previous restriction where bean subtype attributes had to be listed first in JSON objects when using the Bean.subTypeProperty() annotation. The previous behavior was not strictly JSON-compliant since JSON objects are supposed to consist of unordered lists of key/value pairs. While targeted for JSON, the restriction is also lifted for all other parsers.
  • New fluent-style BeanMap.load() methods for initializing bean maps.
  • HtmlDocSerializer will now embed the data portion of the output in a <div id='data'> element to make it easier to extract the data portion of the page in Javascript in browsers.
REST Server API updates
  • New RestRequest.getJavaMethod() method for getting access to the method used to handle a request. Useful for accessing the method name or annotations during requests, such as in calls to RestGuard.guard(RestRequest,RestResponse).
  • Fixed bug when using Jetty where you tried to read text input after a header was written.
  • Added new string variables $A{...} (request attributes) and $P{...} (request parameters) to RestServlet.createRequestVarResolver(RestRequest).

5.1.0.4 (Aug 25, 2014)

Juno 5.1.0.4 is a minor update.

  • New RestServlet.getPath() method.
  • New SerializerContext.getJavaMethod() and ParserContext.getJavaMethod() to allow access to REST methods that invoked the serializers or parsers. For example, can be used to access additional annotations on REST methods to perform special handing during serialization or parsing.
  • Better behavior on overriding of filters in BeanContext.addTransforms(Class[]). Previously, adding multiple conflicting filters resulted in random behavior. Now filters are overridden when multiple matching filters are applied.
  • Allow HtmlDocSerializerContext properties to be set via Serializer.setProperty(String,Object). Previously, these could only be defined through override properties (e.g. through REST class and method annotations).
  • Fixed memory leak in XML parser.

5.1.0.5 (Sept 1, 2014)

Juno 5.1.0.5 is a moderate update.

  • New Redirect class that simplifies performing redirections in REST methods.
  • New pluggable ResponseHandler class and @RestResource(responseHandlers) annotation for defining customer response handlers for special kinds of POJOs.
  • New method UrlEncodingSerializer.serializeUrlPart(Object) method.
  • New method RestRequest.getServletURIBuilder() for construcing servlet-based URLs more efficiently.
  • New method RestResponse.getNegotiatedOutputStream() that uses encoders if a match is found, and RestResponse.getOutputStream() that just return the underlying output stream without any modifications.
  • Fixed bug where some properties were not being propagated correctly when using CoreObject.setProperties(ObjectMap) on serializer and parser subclasses.
  • Fixed bug in HtmlSerializer where URL keys in Maps were not being serialized as hyperlinks.
  • Fixed bug in JsonSerializer where "_class" and "items" attributes were not quoted in strict mode when using SERIALIZER_addClassAttrs feature.
  • Fixed bug where Content-Encoding andCharacter-Encoding headers were being set when calling RestResponse.getOutputStream(). These should not be set if interacting with the output streams at a low level.
  • Eliminated various convenience RestResponse.sendRedirect(...) methods due to the introduction of the Redirect class.

5.1.0.6 (Sept 21, 2014)

Juno 5.1.0.6 is a moderate update.

  • Simplified API for PojoSwap. Since it's rarely used, the beanContext parameter was replaced with a PojoSwap#getBeanContext() method on the class.
  • New simplified way of defining POJO filters without needing to extend PojoSwap. See SurrogateSwap for details.
  • New @Html annotation. Will allow the definition of standard XHTML DTOs in future releases. For now, Img is an example of defining an XHTML element using Juno DTOs.
  • JsonParser now ignores trailing ';' characters in input so that it can parse strings of the form "var x = {'foo':'bar'};".
  • New TumblrParserResource in the samples war file showing how to combine the REST client and server APIs into a single resource in order to download Tumblr blogs and convert the response into any supported response content type.

5.1.0.7 (Oct 5, 2014)

Juno 5.1.0.7 is a moderate update.

  • Improved error handling.
  • New ParserContext.PARSER_debug and SerializerContext.SERIALIZER_debug. settings for logging additional information for debugging problems.
  • New SERIALIZER_ignoreRecursions setting for explicitly ignoring recursions when serializing models. Previously, the SERIALIZER_detectRecursions setting did this, but now it simply looks for recursions and throws exceptions when they occur.
  • Improved handling of StackOverflowErrors. When SERIALIZER_detectRecursions is enabled, a useful error message is displayed showing the exact chain of objects that resulted in the stack overflow.
  • Bug fixes in ResultSetList for Oracle and SQL Server.
  • Serializers and parsers can now access HTTP request attributes, parameters, and headers through SerializerContext.getProperties() and ParserContext.getProperties().
  • Removed media-type and encoding attributes from SerializerContext and ParserContext since these are now available through context properties, and are typically not used.
  • XmlParser now accepts application/xml.
  • Improved handling of bean property serialization when multiple matching pojo filters for the bean property class exist.
  • Improved concurrency on BeanContext class.
  • Fixed bug in Traversable that was causing it to be executed even if the servlet extra path info was empty.
  • Fixed bug in Traversable where it was not picking up filters and properties defined on REST Java methods.

5.1.0.8 (Oct 25, 2014)

Juno 5.1.0.8 is a moderate update, focused primarily on performance improvements.

  • Improved performance on JSON and URL-Encoding parsers by approximately 50% on large data sets.
    • Rewrote ParserReader class to handle it's own buffering. The change allowed several optimizations to be made when dealing with JSON and URL-Encoding text by avoiding char array copies.
    • Added a estimatedSize parameter to the Parser parse methods to optimize buffering when the input size is known beforehand.
  • Revamped the BeanContext API to perform better in multi-threaded environments.
    • Introduced a new BeanPropertyStore class that handles creation of BeanContext objects. This allows BeanContext objects to be considered immutable, and therefore cacheable/reusable by the framework. While this was technically possible to cache these objects beforehand, it relied on a locking mechanism to prevent bean contexts from being modified after being created. The new mechanism is much more straightforward.
  • Modifications to the org.apache.juneau.rest.client APIs to make it easier to work with custom Apache HTTP clients.
    • Added overridable RestClient#createHttpClient() to allow customized subclasses to construct customized HTTP clients.
    • Removed the DefaultRestClient class since it's now fully redundant with RestClient.
    • Added RestClient.shutdown() method for cleaning up the internal HTTP client when you're done using a REST client.

5.1.0.9 (Dec 1, 2014)

Juno 5.1.0.9 is a major update. There weren't very many code changes, but the source has been made a part of Jazz Foundation. This required some restructuring of the project. The project on Jazz Hub will eventually be discontinued. However, the libraries on IBM Community Source will continue to be updated regularly.

  • Project split up into 3 separate bundles:
    • org.apache.juneau - Core serializers and parsers.
    • org.apache.juneau.rest - REST server component.
    • org.apache.juneau.rest.client - REST client component.
  • Code changes to facilitate breaking up bundles:
    • org.apache.juneau.rest.labels.Link class moved to Link.
    • References to org.apache.juneau.rest.RestException in Encoder class changed to IOException.
  • Changed configuration names for consistency with Jazz Framework.
  • New RestClient.execute(HttpUriRequest) method that allows subclasses to handle their own HTTP request execution.
  • Changes in JazzRestClient to handle introduction of SSO support in v6.
  • &plainText debug feature was broken.
  • Removed double-buffering in RestRequest.
  • Metadata cleanup, Find Bug fixes.

5.1.0.10 (Dec 23, 2014)

Juno 5.1.0.10 is a moderate update.

Core
Server
  • Fixed major issue that prevented parsing URL-Encoded form posts into POJOs. Calling HttpServlet.getParameter(String) was forcing the underlying servlet code to process the HTTP body itself, preventing the UrlEncodingSerializer class from being able to parse the content. Updated code no longer inadvertantly calls this method.
  • New RestRequest.getQueryParameter(String), RestRequest.hasQueryParameter(String), and RestRequest.hasAnyQueryParameters(String[]) methods that only look for parameters in the URL query string to prevent loading and parsing of URL-Encoded form posts.
  • New @QParam and @HasQParam annotations for accessing query parameters from the URL query string.
  • &plainText parameter can now specify a false value.
  • Removed properties parameters from RestServlet.onPreCall(RestRequest) and RestServlet#onPostCall(RestRequest,RestResponse) methods since the properties are already accessible through RestRequest.getProperties().
  • Added UonSerializer and UonParser to serializer and parser lists on BasicRestServlet and RestServletJenaDefault.
Client
  • Moved to Apache HttpClient 4.3 to match Jazz 6.0.
  • Renamed RestResponseEntity to RestRequestEntity.
  • Improved performance on URL-Encoded form posts by serializing directly to output stream instead of serialized to string first.
  • New methods on RestClient class that makes it easier to associate serializer and parser attributes with registered serializer and parser:
    • RestClient#setProperty(String,Object)
    • RestClient#setProperties(ObjectMap)
    • RestClient#addNotBeanClasses(Class[])
    • RestClient.addTransforms(Class[])
    • RestClient#addImplClass(Class,Class)
  • Renamed RestClient.shutdown() to RestClient.close() to mirror change in Apache API.
Samples
  • New CodeFormatterResource for quickly formatting Java and XML code samples in Javadocs.
  • New UrlEncodedFormResource for showing how to work with URL-Encoded form posts.

5.1.0.11 (Feb 14, 2015)

Juno 5.1.0.11 is a moderate update.

Core
  • Additions to @Html bean annotation.
    • New @Html(noTables) annotation that prevents arrays/Collections from being serialized as tables.
    • New @Html(noTableHeaders) annotation that prevents HTML tables from having header rows.
  • Several improvements to URL-Encoding support.
    • Improved whitespace handling in UonParser.
    • New UonParserContext.UON_whitespaceAware property for controlling whether whitespace is ignored.
    • New UrlEncodingContext.URLENC_expandedParams property for controlling whether arrays/Collections should be serialized/parsed as multi-part parameters.
    • New @UrlEncoding(expandedParams) annotation that specifies that bean properties of type array/Collection be serialized as multi-part parameters (e.g. &key=val1&key=val2).
  • New JsonSerializerContext.JSON_escapeSolidus property for controlling whether slash characters should be escaped.
  • New TeeOutputStream and TeeWriter classes.
  • New ClassMeta.isInstance(Object) method.
  • Performance improvements when using the BeanMap.add(String,Object) method. Array properties are stored in a temporary list cache until BeanMap.getBean() is called.
  • New BeanPropertyMeta.add(BeanMap,Object) method for adding values to Collection and array properties.
  • Config INI files now support keys with name "*".
Server
  • REST method parameters can now be generic types (e.g. @Param("foo") Map<String,Integer> foo). This applies to headers, attributes, and parameters.
  • New @Param(multipart) and @Query(multipart) annotations for handling multi-part GET and POST parameters.
  • GET parameters are now CASE-SENSITIVE per W3C standards.
    • &Content must now be specified as &content.
    • &Method must now be specified as &method.
    • &debug must now be specified as &debug=true.
    • &plainText must now be specified as &plainText=true.
    • &notrace must now be specified as &noTrace=true.
  • Performance improvements around query parameters.
  • New methods on RestRequest for handling multi-part parameters:
    • RestRequest.getParameters(String,Class)
    • RestRequest#getQueryParameters(String,Class)
  • Fixed Jetty issue in RestResponse.setHeader(String,String) where setting the Content-Type through this method was inconsistent with the behavior in WAS/Tomcat.
  • &noTrace=true now prevents any errors from being logged in log file.
  • Workaround for Jetty issue where ServletContext.getContextPath() always ends with "null".
  • RestServletProperties.REST_allowMethodParam is now true by default on all subclasses of BasicRestServlet and RestServletJenaDefault.
Client
  • New method RestCall.allowRedirectsOnPosts(boolean).
  • New method RestCall.peekInputStream() allows you to read response bodies without interrupting execution flow.
  • New method Session.toString() now useful for debugging purposes. Shows all request/response headers and bodies.
  • RestCallException now includes HttpResponse object for easier debugging.
  • New method RestClient.addListener(RestClientListener) for registering request/response listeners.
  • New RestClient.setClassLoader(ClassLoader) method.
  • TLS support in JazzRestClient.
Other changes
  • samples.ear and samples.war projects have been replaced with an OSGi bundle with activated servlets in juno.samples.

5.1.0.12 (Mar 28, 2015)

Juno 5.1.0.12 is a minor update.

Core
  • Fixed ConfigFile.isEmpty() method.
  • Changed behavior on UonParser to not treat '~' characters as escapes unless followed by one of the following characters: ( ) , $ = ~.
Client
  • New class RestCallInterceptor. Allows responses to be inspected and modified before being processed. Replaces RestClientListener class.
  • Minor connection cleanup fixes.

5.1.0.13 (Apr 24, 2015)

Juno 5.1.0.13 is a minor update.

Core
  • ClassMeta.newInstance() method can now create new instances of arrays.
  • Arguments passed to Link are now serialized using UrlEncodingSerializer, so arbitrary POJOs can now be passed as arguments.
  • New date filters: org.apache.juneau.transforms.Datefilter.ISO8601DTZP and org.apache.juneau.transforms.Datefilter.SimpleP.
  • New HtmlDocSerializerContext.HTMLDOC_nowrap setting for HtmlDocSerializer class. Adds "* {white-space:nowrap}" to the style header to prevent word wrapping.
  • Fixed bug in UonParser where passing in a blank value on an array or collection type in a form post would cause a ClassCastException. New behavior creates an empty array or Collection.
  • Improved implementation of UrlEncodingSerializer.serializeUrlPart(Object) method.
Server
  • RestConverter API fixed to handle the existence of POJO filters. Introspectable/Queryable/Traversable classes can now work with filtered POJOs.
  • @RestResource(messages) annotation can now be defined on super and subclasses so that NLS messages can be defined in multiple resource bundles.
  • Performance improvements in RestServletNls class.
  • Fixed bug where two REST java methods mapped to the same path pattern wasn't triggering an exception when it was supposed to.
Client
  • New RestCall.setRedirectMaxAttempts(int) method to prevent endless redirection loops.
  • New RestCall#setRetryable(int,long,RetryOn) method to automatically retry on failed connection attempts.
  • New RestCallInterceptor.onRetry(RestCall,int,HttpRequest,HttpResponse) method for listening in on retry attempts.

5.1.0.14 (May 10, 2015)

Juno 5.1.0.14 is a moderate update.

The major addition is support for Remoteable Services, the ability to invoke server-side POJO methods through client-side proxy interfaces.

Core
Client
  • New methods in RestClient for working with remoteable services:
    • RestClient.setRemoteableServletUri(String)
    • RestClient#getRemoteableProxy(Class)
Server
  • Added a default OPTIONS page to BasicRestServlet and RestServletJenaDefault.
  • RestServletProperties.REST_allowMethodParam has been enhanced to allow you to explicitly specify which HTTP methods can be used in the &method parameter.
  • New methods added to RestRequest:
    • RestRequest.getParser()
    • RestRequest.getReaderParser()

5.1.0.15 (May 24, 2015)

Juno 5.1.0.15 is a minor update.

Core
  • New properties in SerializerContext:
    1. SerializerContext.SERIALIZER_relativeUriBase
    2. SerializerContext.SERIALIZER_absolutePathUriBase
    These replace the SERIALIZER_uriAuthority and SERIALIZER_uriContext properties.
  • Improvements in CsvSerializer.
Server
  • New properties in RestServletProperties:
    1. REST_defaultCharset
    2. REST_servletURI
    3. REST_relativeServletURI
  • Improvements involving path calculations when servlets deployed outside of a war file with a context root.
Client
  • New methods in RestCall:
    1. RestRequest.getHeader(String,Class)
    2. RestRequest.getHeader(String,Object,Class)
    3. RestRequest.getHeader(String,Type,Type...)
    4. RestRequest.getQueryParameter(String,Class)
    5. RestRequest.getQueryParameter(String,Object,Class)
    6. RestRequest.getQueryParameter(String,Type,Type...)
    7. RestRequest.getQueryParameter(String,Object,Type,Type...)
    8. RestRequest.getQueryParameters(String,Class)
    9. RestRequest.getQueryParameters(String,Type,Type...)
    10. RestRequest.getFormDataParameter(String,Class)
    11. RestRequest.getFormDataParameter(String,Object,Class)
    12. RestRequest.getFormDataParameters(String,Class)
    13. RestRequest.getFormDataParameter(String,Type,Type...)
    14. RestRequest.getFormDataParameters(String,Type,Type...)
    15. RestRequest.getPathParameter(String,Class)
    16. RestRequest.getPathParameter(String,Type,Type...)
    17. RestRequest.getBody(Class)
    18. RestRequest.getBody(Type,Type...)

5.1.0.16 (June 28, 2015)

Juno 5.1.0.16 is a moderate update.

Core
  • New methods on ClassMeta that eliminates language-specific code in the general class metadata.
    • ClassMeta.getXmlMeta()
    • ClassMeta.getJsonMeta()
    • ClassMeta.getHtmlMeta()
    • ClassMeta.getUrlEncodingMeta()
    • ClassMeta.getRdfMeta()
  • New JsonType.ANY enum.
  • New @Html(asPlainText) annotation.
  • New HtmlDocSerializerContext.HTMLDOC_cssImports property.
  • Significant changes to RDF support.
    • New @Rdf and @RdfSchema annotations. These replace the use of defining namespaced through the XML annotations, and allows XML and RDF to be serialized using different namespaces.
    • Support for serializing arrays/collections as RDF bags, RDF lists, and multi-valued properties.
    • Fixed warning message about "tab" setting when using the N3/Turtle serializers.
  • New SerializerContext.SERIALIZER_sortCollections and SerializerContext.SERIALIZER_sortMaps properties.
  • FindBug fixes.
Server
  • New RestRequest.getServletParentURI() method.
  • New $R{servletParentURI} variable.
  • Removed final modifier from ChildResourceDescriptions.
Samples
  • Added source code links to examples.

5.1.0.17 (Aug 3, 2015)

Juno 5.1.0.17 is a major update.

Core
  • BeanMap.get(Object) and BeanMap.put(String,Object) now automatically performs filtering if filters are defined on the bean property or bean property class.
    • Deleted the following methods which are now unnecessary:
      • BeanMap.getFiltered(String)
      • BeanMap.putFiltered(String,Object)
      • BeanMapEntry.getFiltered(String)
      • BeanMapEntry.putFiltered(String,Object)
      • BeanMapEntry.putFiltered(String,Object)
      • BeanPropertyMeta.getFiltered()
      • BeanPropertyMeta.setFiltered(Object)
      • BeanPropertyMeta.getTransformedClassMeta()
    • BeanPropertyMeta.getClassMeta() now returns the filtered type of the property.
  • StringVarResolver now has support for chained resolvers.
  • StringVarResolver now resolves variables inside resolved values. i.e. if a resolved variable value itself contains a variable, it now resolves that variable too.
  • Fixed bug where inner interface classes being used in RestResource.filters() were being interpreted as surrogate classes because they have hidden 1-arg constructors due to being inner classes.
  • Fixed bug in MultiSet where exception was being thrown if last set was empty.
  • New ZipFileList class for providing efficiently zipped directories through the REST interface.
  • New RdfProperties.RDF_useXmlNamespaces property.
  • New XmlParserContext.XML_preserveRootElement property.
  • Worked around bug in Sun VM on OS/X where XML parser was throwing an exception when trying to set a reporter.
Server
  • New ZipFileListResponseHandler class.
  • Simplified labels in servlet resource bundles:
    • "[ClassName].ResourceDescription" is now "[ClassName].label".
    • "[ClassName].MethodDescription.[methodName]" is now "[ClassName].[methodName]".
  • Several changes to RestRequest:
    • Added new methods:
      • RestRequest.getQueryParameterMap()
      • RestRequest.getQueryParameterNames()
      • RestRequest.getPathInfoUndecoded()
      • RestRequest.getPathRemainderUndecoded()
      • RestRequest.getTrimmedRequestURI()
      • RestRequest.getTrimmedRequestURL()
      • RestRequest.getServletTitle()
      • RestRequest.getServletDescription()
      • RestRequest.getMethodDescription()
    • Behavior changes to HttpServletRequestWrapper.getPathInfo() to follow Servlet specs. Returns null instead of blank for no path info.
    • RestRequest.getPathRemainder() now automatically decodes the path remainder. Use RestRequest.getPathRemainderUndecoded() to get the unencoded path remainder.
    • Bug fixes in RestRequest.getRequestParentURI() when servlet is mapped to "/*".
    • Bug fixes in RestRequest.getServletURI() when servlet is mapped to "/*".
  • New string replacement variables:
    • $R{contextPath} - Returns value from RestRequest.getContextPath()
    • $R{methodDescription} - Returns value from RestRequest.getMethodDescription()
    • $R{resourceTitle} - Returns value from RestRequest.getServletTitle()
    • $R{resourceDescription} - Returns value from RestRequest.getServletDescription()
    • $R{trimmedRequestURI} - Returns value from RestRequest.getTrimmedRequestURI()
    • $E{var} - Environment variables.
  • Added methods RestServlet.getDescription(RestRequest) and RestServlet.getLabel(RestRequest).
  • BasicRestServlet and RestServletJenaDefault now provide default HTML titles and descriptions:

    @Property(name=HTMLDOC_title, value="$R{resourceTitle}"), @Property(name=HTMLDOC_description, value="$R{resourceDescription}")

  • Options pages on BasicRestServlet and RestServletJenaDefault now provide default descriptions and back links: and descriptions:

    @Property(name=HTMLDOC_navlinks, value="{back:'$R{servletURI}"), @Property(name=HTMLDOC_description, value="Resource options")

  • New BasicRestServletGroup class.
  • Removed RestServletProperties.REST_trimTrailingUriSlashes and RestServletProperties.REST_pathInfoBlankForNull.
  • New annotations for providing labels and descriptions. Useful if you don't plan on having to support other languages, so you don't want to provide labels in resource bundles.
  • Support for sorting resources by name in ChildResourceDescriptions.
Samples
  • Added /tempDir/upload showing how to use ServletFileUpload with multipart form posts.

5.1.0.18 (Aug 5, 2015)

Juno 5.1.0.18 is a minor update affecting the server component only.

Server
  • Fixed bug where localized strings weren't resolving when using chained resource bundles.
  • Servlet and method labels and descriptions can now contain embedded string variables.
  • New RestMethod.input() and RestMethod.responses() annotations. These replace the various description annotations added 2 days ago with a simpler design.
  • New methods on RestServlet:
    • RestServlet.getMethodDescription(String,RestRequest) so that subclasses can override the method description in the OPTIONS page.
    • RestServlet.createRequestVarResolver(RestRequest) so that subclasses can override and augment the variable resolver.
    • RestServlet.resolveChild(Class) and RestServlet.replaceChild(RestServlet) classes that allows customized resolution of servlet instances (e.g. if services are defined in OSGi).
  • Reverted the MethodDescription back to 5.1.0.16 since it was being used by someone.

5.1.0.19 (Aug 15, 2015)

Juno 5.1.0.19 is a minor update in terms of core functionality. But it introduces a Microservices project for building REST microservices and docker containers.

Core
Client
Server
  • New RestRequest.getHeaders() method.
  • New RestResponse.getUnbufferedWriter() method.
  • Fixed bug that was preventing x-response-headers parameter from working correctly.
  • Added @Bean.properties annotations to the various classes in org.apache.juneau.rest.labels so that the order of the bean properties are consistent on all JVMs. On IBM JVMs this is unnecessary because the order of the properties as defined in the class are stored in the bytecode. Other JVMs such as OpenJRE do not implement this feature causing the bean properties to be in random order.
  • New ResourceDescription.ResourceDescription(RestRequest,String,String) constructor.

5.1.0.20 (Sept 5, 2015)

Juno 5.1.0.20 is a moderate update. The biggest improvement is the ability to associate external INI config files with REST servlets using the ConfigFile functionality.

Core
  • Significant API changes to org.apache.juneau.config API.
    • ConfigFile is now thread safe and can be shared across multiple threads.
    • New ConfigMgr class for managing configuration files.
    • Serializers and parsers can be associated with config files for storing and retrieving POJOs. Default support provided for JSON.
  • New SimpleHtmlWriter class. Can be used for simple HTML DOM construction.
  • New ProcBuilder class for calling external processes.
  • New ObjectMap.remove(Class,String,Object) method.
  • "class='link'" added to links generated by HtmlDocSerializer.
  • New EncoderGroup#append(EncoderGroup) method.
  • New HtmlDocSerializerContext.HTMLDOC_addLinks configuration property.
  • Modified the Parser.createContext(ObjectMap,Method,Object) method. Outer context objects can be passed in to create instances of non-static inner classes.
  • Fixed bug in HtmlStrippedDocSerializer where exception was thrown when trying to serialize primitive arrays.
  • JsonParser now handles parsing JSON boolean/numeric values as strings to bean properties of type boolean or number.
  • UrlEncodingSerializer and UrlEncodingParser now represent arrays and collections as key-value pairs where the keys are numbers (e.g. "?0=foo&1=bar").
  • Various internal improvements to IOPipe.
  • New ReflectionUtils.getResource(Class,String) method.
  • StringUtils.parseNumber(String,Class) now returns zero for empty strings. This affects the way most parsers handle blank values.
Server
  • You can now parse into non-static inner classes of a servlet for parameters/attributes/content. Useful if you like to define your marshaller beans inside your servlet.
  • Changes to RestServlet:
    • New methods for accessing external INI config files:
      RestServlet.getConfig()
      RestServlet.createConfigFile()
    • New "$C{...}" variable that resolve to INI config file values.
    • New "$UE{...}" variable that URL-encodes the value inside the variable.
    • New convenience methods for retrieving classpath resource files:
      RestServlet.getResource(String)
      RestServlet.getResourceAsString(String)
      RestServlet.getResource(Class,String,String). Useful if you want to load predefined POJOs from JSON files in your classpath.
    • New RestServlet.handleNotFound(int,RestRequest,RestResponse) method for customized handling of when a resource or method was not found.
  • BasicRestServlet now automatically processes "/favicon.ico" requests by overriding the new RestServlet.handleNotFound(int,RestRequest,RestResponse) method.
  • New RestRequest methods:
    • RestRequest.resolveVars(String)
    • RestRequest.getVarResource(String)
    • RestRequest.getConfig()
  • New RestResponse methods:
  • New @RestMethod(encoders) and RestMethod.inheritEncoders() annotations. Allows encoders to be fine-tuned at the method level.
  • New @RestResource(config) annotation for associating external ConfigFile config files with servlets.
  • ResourceLink.
  • New org.apache.juneau.rest.matchers package for commonly-used RestMatchers:
Microservice
  • New juneau-microservice.jar file that encapsulates all 3 juneau jars with code necessary for creating fast and efficent jetty-powered REST microservices.
    Contains the following:
    • Jetty 8.0
    • Apache HttpClient 4.3.5
    • Apache Commons FileUpload 1.3.1
  • Microservice now supports Java 6 (previously required Java 7)

5.2.0.0 (Dec 30, 2015)

Juno 5.2.0.0 is a major update. Major changes have been made to the microservice architecture and config INI file APIs.

Core
Client
  • Upgraded to use Apache HttpClient 4.5.
  • New classes:
  • Removed org.apache.juneau.rest.client.LaxRedirectStrategy. Use HTTP Client equivalent.
  • New methods on RestCall:
  • New lifecycle listener methods on RestCallInterceptor:
  • New methods on RestClient:
    • RestClient.setBasicAuth(String,int,String,String)
    • RestClient.logTo(Level,Logger)
    • RestClient.setRootUrl(String)
    • RestClient.enableSSL(SSLOpts)
    • RestClient.enableLaxSSL()
    • RestClient.doCall(HttpMethod,Object,Object)
    • RestClient.createHttpClientBuilder()
  • New passthrough methods on RestClient defined on HttpClientBuilder:
    • RestClient.setRedirectStrategy(RedirectStrategy)
    • RestClient.setDefaultCookieSpecRegistry(Lookup)
    • RestClient.setRequestExecutor(HttpRequestExecutor)
    • RestClient.setSSLHostnameVerifier(HostnameVerifier)
    • RestClient.setPublicSuffixMatcher(PublicSuffixMatcher)
    • RestClient.setSSLContext(SSLContext)
    • RestClient.setSSLSocketFactory(LayeredConnectionSocketFactory)
    • RestClient.setMaxConnTotal(int)
    • RestClient.setMaxConnPerRoute(int)
    • RestClient.setDefaultSocketConfig(SocketConfig)
    • RestClient.setDefaultConnectionConfig(ConnectionConfig)
    • RestClient.setConnectionTimeToLive(long,TimeUnit)
    • RestClient.setConnectionManager(HttpClientConnectionManager)
    • RestClient.setConnectionManagerShared(boolean)
    • RestClient.setConnectionReuseStrategy(ConnectionReuseStrategy)
    • RestClient.setKeepAliveStrategy(ConnectionKeepAliveStrategy)
    • RestClient.setTargetAuthenticationStrategy(AuthenticationStrategy)
    • RestClient.setProxyAuthenticationStrategy(AuthenticationStrategy)
    • RestClient.setUserTokenHandler(UserTokenHandler)
    • RestClient.disableConnectionState()
    • RestClient.setSchemePortResolver(SchemePortResolver)
    • RestClient.setUserAgent(String userAgent)
    • RestClient.setDefaultHeaders(Collection)
    • RestClient.addInterceptorFirst(HttpResponseInterceptor)
    • RestClient.addInterceptorLast(HttpResponseInterceptor)
    • RestClient.addInterceptorFirst(HttpRequestInterceptor)
    • RestClient.addInterceptorLast(HttpRequestInterceptor)
    • RestClient.disableCookieManagement()
    • RestClient.disableContentCompression()
    • RestClient.disableAuthCaching()
    • RestClient.setHttpProcessor(HttpProcessor)
    • RestClient.setRetryHandler(HttpRequestRetryHandler)
    • RestClient.disableAutomaticRetries()
    • RestClient.setProxy(HttpHost)
    • RestClient.setRoutePlanner(HttpRoutePlanner)
    • RestClient.disableRedirectHandling()
    • RestClient.setConnectionBackoffStrategy(ConnectionBackoffStrategy)
    • RestClient.setBackoffManager(BackoffManager)
    • RestClient.setServiceUnavailableRetryStrategy(ServiceUnavailableRetryStrategy)
    • RestClient.setDefaultCookieStore(CookieStore)
    • RestClient.setDefaultCredentialsProvider(CredentialsProvider)
    • RestClient.setDefaultAuthSchemeRegistry(Lookup)
    • RestClient.setContentDecoderRegistry(Map)
    • RestClient.setDefaultRequestConfig(RequestConfig)
    • RestClient.useSystemProperties()
    • RestClient.evictExpiredConnections()
    • RestClient.evictIdleConnections(long,TimeUnit)
  • JazzRestClient now supports OIDC authentication.
  • These classes are now deprecated and will be removed in a future release:
    • org.apache.juneau.rest.client.jazz.CertificateStore
    • org.apache.juneau.rest.client.jazz.ICertificateValidator
    • org.apache.juneau.rest.client.jazz.ITrustStoreProvider
    • org.apache.juneau.rest.client.jazz.LenientCertificateValidator
    • org.apache.juneau.rest.client.jazz.SharedTrustStoreProvider
    • org.apache.juneau.rest.client.jazz.ValidatingX509TrustManager
Server
  • New ReaderResource class. Represents the contents of a text file with convenience methods for resolving StringVar variables and adding HTTP response headers. REST Java methods can return instances of these to serialize Readers containing text with StringVarResolver variables in them.
  • New StreamResource class. REST Java methods can return instances of these to serialize OutputStreams.
  • Fixed a bug in the stack trace hash algorithm in RestException.
  • New methods in RestRequest:
    • RestRequest.getReaderResource(String) - Replaces getVarResource(String).
    • RestRequest.getReaderResource(String,boolean)
    • RestRequest.getReaderResource(String,boolean,String)
  • Changes in RestResponse:
    • Don't set Content-Encoding: identity when no encoding is used. Some clients don't interpret it correctly.
  • New methods in RestServlet:
    • RestServlet.getChildClasses() - Programmatic equivalent to @RestResource(children) annotation.
    • RestServlet.shouldLog(HttpServletRequest,HttpServletResponse,RestException)
    • RestServlet.shouldLogStackTrace(HttpServletRequest,HttpServletResponse,RestException)
    • RestServlet.logObjects(Level,String,Object[])
    • RestServlet.resolveStaticFile(String)
    • RestServlet.createStyleSheet()
    • RestServlet.createFavIcon()
    • RestServlet.createStaticFilesMap()
    • RestServlet.getConfigMgr()
  • Removed JsoParser from BasicRestServlet and RestServletJenaDefault. These may represent a security risk if not handled correctly, so removed them as a precaution.
  • Removed RestServletProperties.REST_htDocsFolder. Replaced with @RestResource(staticFiles).
  • New annotations on @RestResource.
  • Eliminated org.apache.juneau.rest.jaxrs.JsonProvider class. Some JAX-RS implementations use code scanning to find providers, so if you were using DefaultJenaProvider, it would pick up JsonProvider as well. It's easy enough to create your own implementation if needed.
  • OPTIONS pages now specify consumes and produces fields instead of accept and contentType which was confusing.
  • Eliminated properties from OPTIONS pages.
  • New ResourceLink.ResourceLink(String,RestRequest,String,Object[]) constructor.
  • New response handlers:
    • StreamableHandler - Allows REST Java methods to return instances of Streamable.
    • WritableHandler - Allows REST Java methods to return instances of Writable.
  • New DevOps stylesheet.
  • Servlet initialization and HTTP requests are now logged at FINE level.
  • Added abstract modifier on various RestServlet subclasses to indicate that they're meant to be subclassed.
  • New RestUtils.trimPathInfo(StringBuffer,String,String) method.
Microservice
  • Completely revamped API.
  • New Microservice class that serves as a generic interface for microservices and their lifecycles.
  • New RestMicroservice class that implements a microservice consisting of a REST interface.
    • REST resources and configuration settings can be defined through either manifest files or config files.
    • Enhanced logging support.
    • Easy-to-configure SSL support.
    • BASIC auth support.
    • Automatic restartability if the config file changes.
  • Eliminated org.apache.juneau.microservice.Main class. This is replaced by the microservice classes defined above.
  • Resource and ResourceGroup classes now support the following new string variables:
    • "$A{key,default}"" - Command line arguments.
    • "$MF{key,default}"" - Manifest file entries.
  • CSS stylesheet now configurable through config file entry "REST/stylesheet".
  • New BasicRestServletJena class if you want your REST interface to support RDF.
  • Eliminated the following classes:
    • org.apache.juneau.microservice.RootResource
    • org.apache.juneau.microservice.SampleResource
  • New predefined reusable resources:
    • ConfigResource - REST resource for viewing and editing microservice config file.
    • LogsResource - REST resource for viewing log files.
    • SampleRootResource - Sample REST resource that contains the config and logs resource as children.
    • ShutdownResource - REST resource for stopping the microservice JVM. Useful for testing purposes.
Samples
  • Converted to a REST microservice.
  • Look-and-feel changed to IBM DevOps.
Documentation Updates
  • org.apache.juneau.microservice - New package-level javadoc.
  • org.apache.juneau.config - New package-level javadoc.
  • StringVarResolver - New documentation.
  • org.apache.juneau.rest.client - New package-level javadoc.
  • Overview / Samples - New section.
  • org.apache.juneau.transform / Stop Classes - New section.
  • org.apache.juneau.rest - Extensive updates.

5.2.0.1 (Mar 23, 2016)

Juno 5.2.0.1 is a moderate update.

com.ibm.team.juno
Server
Client
  • Fixed potential issue in RestClient where the HTTP connection pool could end up exhausted if an error occurred.
  • Improved thread safety on RestClient.
  • New warning message is logged if a RestClient is garbage collected without being closed: "WARNING: RestClient garbage collected before it was finalized."

6.0.0 (Oct 3, 2016)

Juneau 6.0.0 is a major update.

The major change is rebranding from "Juno" to "Juneau" in preparation for donation to the Apache Foundation.

org.apache.juneau
  • Major changes around how serializer and parser class properties are defined to improve performance and concurrency.
    • New PropertyStore class - Used for creating context objects.
    • New Context class - Read-only configurations for serializers and parsers.
    • New Session class - One-time use objects used by serializers and parsers.
    • All context context properties can now also be specified via system properties.
  • Refactored serializer and parser APIs for more consistency between stream-based and character-based serializers and parsers.
    • More consistent handling of exceptions.
    • More consistent method declarations.
  • Refactored var resolver API and added them to a new package - org.apache.juneau.svl.
    • Support for stream-based variables - StreamedVar.
    • Added support for context and session objects.
  • Eliminated "_class" properties and replaced them with "_type" properties. The class properties were a little-used feature where we would serialize fully-qualified class names when the class type could not be inferred through reflection. It's been replaced with bean type names and bean dictionaries. Instead of class names, we serialize "_type" properties whose name is the type name defined on the bean being serialized. The parsers use a 'dictionary' of bean classes to resolve those names to actual bean classes. The following features were added to enable this support: In addition, the @Bean(typeName) value replaces the @Xml(name) annotation, and the "type" and "_class" attributes in the XML and HTML serializers have been standardized on a single "_type" attribute.
  • Refactor bean filter support to use BeanFilterBuilder class. Allows the BeanFilter class to use final fields.
  • MessagePack support.
  • Serializers can now serialize directly to Files. See Serializer.serialize(Object,Object)
  • Parsers can now parse directly from Files and other types. See Parser.parse(Object,ClassMeta)
  • Parsers will automatically covert numeric input to POJOs that have numeric constructors (e.g. java.util.Date).
  • Renamed 'Filters' to 'BeanFilters' and 'PojoSwaps'. Filters is just too overloaded a term.
  • Internal utility classes moved to a new org.apache.juneau.internal package. These internal utility classes are not meant for consumption outside the Juneau codebase.
  • New methods on Parser:
    • org.apache.juneau.parser.Parser.createSession(ObjectMap,Method,Object)
    • Parser.getMediaRanges()
  • New methods on Serializer:
    • org.apache.juneau.serializer.Serializer.createSession(ObjectMap,Method)
    • Serializer.getMediaRanges()
  • New @Bean(sort) annotation.
  • Added @Bean.properties annotations on various DTO beans to make the ordering consistent between IBM and Oracle JVMs.
    IBM JVMs maintain the order of methods in a class, whereas Oracle JVMs do not.
  • Serializers and parsers now automatically convert Class objects to readable names via ClassUtils.getReadableClassName(Class).
  • Eliminated the ClassFilter class since it's no longer needed.
  • Code and concurrency improvements to SerializerGroup and ParserGroup.
  • Various enhancements to BeanContext.convertToType(Object,Class).
  • New properties on HtmlSerializer:
    • HtmlSerializerContext.HTML_detectLinksInStrings - Automatically detect hyperlinks in strings.
    • HtmlSerializerContext.HTML_lookForLabelParameters - Specify anchor text by appending &label=MyLabel to URL.
    • HtmlSerializerContext.HTML_labelParameter - Specify what URL parameter to use as the anchor text label.
    • HtmlSerializerContext.URI_ANCHOR option for HtmlSerializerContext.HTML_uriAnchorText.
  • Removed generics from BeanPropertyMeta.
  • Introduced new classes to eliminate the references to language-specific metadata in the core metadata classes:
  • Renamed @Transform annotation to @Pojo so that it can be used for various POJO-related behavior, not just associating transforms.
  • Introduced Swagger DTOs.
org.apache.juneau.rest
  • OPTIONS pages replaced with Swagger documents. Lots of changes related to supporting Swagger.
    • Annotation name changes to conform to Swagger specs: @Attr->@Path, @QParam->@Query, @Param->@FormData, @Content->@Body
    • Eliminated ResourceOptions and related code.
    • New annotations and related methods:
  • New RestServletContext.paramFormat context property.
  • New/updated methods on RestServlet:
    • RestServlet.createProperties()
    • RestServlet.createBeanContext(ObjectMap,Class[],Class[])
    • RestServlet.createBeanFilters()
    • RestServlet.createPojoSwaps()
    • RestServlet.createParsers(ObjectMap,Class[],Class[])
    • RestServlet.createUrlEncodingSerializer(ObjectMap,Class[],Class[])
    • RestServlet.createUrlEncodingParser(ObjectMap,Class[],Class[])
    • RestServlet.createConverters(ObjectMap)
    • RestServlet.createDefaultRequestHeaders(ObjectMap)
    • RestServlet.createDefaultResponseHeaders(ObjectMap)
    • RestServlet.createEncoders(ObjectMap)
    • RestServlet.createGuards(ObjectMap)
    • RestServlet.createMimetypesFileTypeMap(ObjectMap)
    • RestServlet.createResponseHandlers(ObjectMap)
  • New client-version annotations:
org.apache.juneau.rest.client
  • Removed the JazzRestClient class.
  • New method RestClient.setClientVersion(String).

6.0.1 (Jan 3, 2017)

Juneau 6.0.1 is a minor update.

org.apache.juneau
  • General improvements to JSON parser.
    • Several fixes to handle obscure edge cases.
  • New properties in ParserContext.
    • ParserContext.PARSER_strict
    • ParserContext.PARSER_inputStreamCharset
    • ParserContext.PARSER_fileCharset
  • Removed JsonParserContext.JSON_strictMode. Replaced by PARSER_strict.
  • byte[] arrays can now be passed to Parser.parse(Object,Class) for reader-based parsers.

6.1.0 (Feb 25, 2017)

Juneau 6.1.0 is a major update.

In particular, this release cleans up the BeanContext API to match the PropertyStore/Context/Session paradigm previously used in the serializer and parser APIs. It also makes several improvements to the HTML and XML serialization support and introduces HTML5 DTO beans.

org.apache.juneau
org.apache.juneau.rest
  • RestRequest now passes locale and timezone to serializers/parsers/transforms.
  • RestRequest.getTimeZone() method.
  • Standardized the following methods in RestRequest to remove dependency on ClassMeta objects and eliminate the need for casts:
    • RestRequest.getHeader(String,Class)
    • RestRequest.getHeader(String,Object,Class)
    • RestRequest.getHeader(String,Type,Type...)
    • RestRequest.getQueryParameter(String,Class)
    • RestRequest.getQueryParameter(String,Object,Class)
    • RestRequest.getQueryParameter(String,Type,Type...)
    • RestRequest.getQueryParameter(String,Object,Type,Type...)
    • RestRequest.getQueryParameters(String,Class)
    • RestRequest.getQueryParameters(String,Type,Type...)
    • RestRequest.getFormDataParameter(String,Class)
    • RestRequest.getFormDataParameter(String,Object,Class)
    • RestRequest.getFormDataParameters(String,Class)
    • RestRequest.getFormDataParameter(String,Type,Type...)
    • RestRequest.getFormDataParameters(String,Type,Type...)
    • RestRequest.getPathParameter(String,Class)
    • RestRequest.getPathParameter(String,Type,Type...)
    • RestRequest.getBody(Class)
    • RestRequest.getBody(Type,Type...)
  • New methods on NameValuePairs
  • Fixed issue where whitespace was not added to UON/URL-Encoding output when &plainText=true specified.

6.2.0 (Apr 28, 2017)

Juneau 6.2.0 is a major update.

org.apache.juneau
  • Revamped the serializer, parser classes to use builders for creation. Serializers and parsers are now unmodifiable objects once they are created. This is a breaking code change that will require adoption.

    /* Creating a new serializer or parser */ // Old way WriterSerializer s = new JsonSerializer().setUseWhitespace(true).pojoSwaps(BSwap.class).lock(); // New way WriterSerializer s = JsonSerializer.create().ws().pojoSwaps(BSwap.class).build(); /* Cloning an existing serializer or parser */ // Old way WriterSerializer s = SimpleJsonSerializer.DEFAULT .clone().setUseWhitespace(true).pojoSwaps(BSwap.class).lock(); // New way WriterSerializer s = SimpleJsonSerializer.DEFAULT .builder().ws().pojoSwaps(BSwap.class).build();

  • Also introduced the following builder classes and related architecture changes to make the built objects unmodifiable:
  • Revamped the config file API to use a build: ConfigFileBuilder.
  • Removed the Lockable interface.
  • New addBeanTypeProperties setting added to serializers to override the SerializerContext.SERIALIZER_addBeanTypeProperties setting for individual serializers in a serializer group:
    • HtmlSerializerContext.HTML_addBeanTypeProperties
    • JsonSerializerContext.JSON_addBeanTypeProperties
    • MsgPackSerializerContext.MSGPACK_addBeanTypeProperties
    • UonSerializerContext.UON_addBeanTypeProperties
    • XmlSerializerContext.#XML_addBeanTypeProperties
    • RdfSerializerContext.RDF_addBeanTypeProperties
  • UON notation serializers and parsers moved into the new org.apache.juneau.uon package.
  • New XmlFormat.VOID format to identify HTML void elements.
  • Tweaks to HTML5 support.
    • Fixed handling of empty non-void elements in HTML serializer.
    • Added style() override methods to all elements.
  • Improvements to Swagger support.
    • New SwaggerBuilder class.
    • Fluent-style setters added to the Swagger beans.
    • Added Swagger examples here and in the org.apache.juneau.dto.swagger javadocs.
  • Improvements to VarResolver.
    • New $IF variable for if-else block logic.
    • $SWITCH variable for switch block logic.
    • Whitespace wasn't being ignored in some cases.
  • HtmlParser can now parse full body contents generated by HtmlDocSerializer.
  • Parse-args supported added to MsgPackParser to allow it to be used in remoteable proxies.
  • Added some convenience classes for constructing collections using a fluent interface:
  • New @Bean(typePropertyName) annotation allows you to specify the name of the "_type" property at the class level.
  • New methods added to HTML5 container beans:
  • New common serializer setting: SerializerContext.SERIALIZER_abridged.
  • Support for defining interface proxies against 3rd-party REST interfaces.
    New package org.apache.juneau.remoteable for all remoteable proxy interface annotations.
    @Remoteable annotation has been moved to this package.
  • Updated doc: 6 - Remoteable Services
  • New doc: 6.1 - Interface proxies against 3rd-party REST interfaces
  • New URL-encoding serializer setting: UrlEncodingSerializerContext.URLENC_paramFormat.
  • New methods on UrlEncodingSerializerBuilder:
    • UrlEncodingSerializerBuilder.paramFormat(String)
    • UrlEncodingSerializerBuilder.plainTextParams()
org.apache.juneau.rest
  • @RestResource annotation can now be applied to any class! You're no longer restricted to subclassing your resources from RestServlet.
    This is a major enhancement in the API. Anything you could do by subclassing from RestServlet should have an equivalent for non-RestServlet classes.
    The only restriction is that the top-level resource must subclass from RestServlet. Child resources do not.

    The majority of code has been split up into two separate classes:
    • RestConfig - A modifiable configuration of a resource. Subclasses from ServletConfig.
    • RestContext - A read-only configuration that's the result of a snapshot of the config.


    The RestServlet class now has the following initialization method that allows you to override the config settings define via annotations:
    • RestServlet.init(RestConfig) - A modifiable configuration of a resource.
    Non-RestServlet classes must have one of the following to allow it to be instantiated:
    • A public T(RestConfig) constructor.
    • A public T() constructor.
    • The parent resource must have a customized RestResourceResolver for instantiating it.

    Non-RestServlet classes can optionally include the following init methods to gain access to the config and context:
    • public init(RestConfig)
    • public init(RestContext)
  • New annotations added to @RestResource to allow non-RestServlet resources to do the same as subclassing directly from RestServlet:
  • New annotations added to @RestResource and @RestMethod to simplify defining page title, text, and links on HTML views:
    • @RestResource(pageTitle)
    • @RestMethod(pageTitle)
    • @RestResource(pageText)
    • @RestMethod(pageText)
    • @RestResource(pageLinks)
    • @RestMethod(pageLinks)

    // Old method @RestResource( properties={ @Property(name=HTMLDOC_title, value="System properties resource"), @Property(name=HTMLDOC_description, value="REST interface for performing CRUD operations on system properties."), @Property(name=HTMLDOC_navlinks, value="{up:'$R{requestParentURI}',options:'?method=OPTIONS'}") } ) // New method @RestResource( pageTitle="System properties resource", pageDescription="REST interface for performing CRUD operations on system properties.", pageLinks="{up:'$R{requestParentURI}',options:'?method=OPTIONS'}" )

    Typically you're going to simply want to use the title and description annotations which apply to both the page title/text and the swagger doc:

    @RestResource( title="System properties resource", description="REST interface for performing CRUD operations on system properties.", pageLinks="{up:'$R{requestParentURI}',options:'?method=OPTIONS'}" )

  • RestResource.stylesheet() can now take in a comma-delimited list of stylesheet paths.
  • StreamResource can now contain multiple sources from a variety of source types (e.g. byte[] arrays, InputStreams, Files, etc...) and is now immutable. It also includes a new StreamResourceBuilder class.
  • Simplified remoteable proxies using the @RestMethod(name="PROXY") annotation on REST methods. Used to expose interface proxies without the need for RemoteableServlet.

    // Server side @RestMethod(name="PROXY", path="/myproxy/*") public IAddressBook getProxy() { return addressBook; } // Client side RestClient client = RestClient.create().rootUrl(samplesUrl).build(); IAddressBook ab = client.getRemoteableProxy(IAddressBook.class, "/addressBook/myproxy");

    See @RestMethod(name) for more information.
  • RestRequest.toString() can be called at any time to view the headers and content of the request without affecting functionality. Very useful for debugging.
  • @RestMethod(name) annotation is now optional. Defaults to "GET".
org.apache.juneau.rest.client
org.apache.juneau.microservice

6.3.0 (Jun 30, 2017)

Juneau 6.3.0 is a major update with significant new functionality for defining proxy interfaces against arbitrary 3rd-party REST interfaces.

org.apache.juneau
  • New package: org.apache.juneau.http.
  • Support for dynamic beans. See @BeanProperty(name).
  • New doc: 2.8 - Virtual Beans
  • New doc: 2.13 - Comparison with Jackson
  • All parsers now allow for numeric types with 'K'/'M'/'G' suffixes to represent kilobytes, megabytes, and gigabytes.

    // Example int i = JsonParser.DEFAULT.parse("123M"); // 123MB

  • New/modified methods on ConfigFile:
    • ConfigFile.put(String,String,String,boolean)
    • ConfigFile.put(String,String,Object,Serializer,boolean,boolean)
    • ConfigFile.getObject(String,Type,Type...)
    • ConfigFile.getObject(String,Parser,Type,Type...)
    • ConfigFile.getObject(String,Class)
    • ConfigFile.getObject(String,Parser,Class)
    • ConfigFile.getObject(String,String,Type,Type...)
    • ConfigFile.getObject(String,String,Parser,Type,Type...)
    • ConfigFile.getObject(String,String,Class)
    • ConfigFile.getObject(String,String,Parser,Class)
    • ConfigFile.getObjectWithDefault(String,Object,Type,Type...)
    • ConfigFile.getObjectWithDefault(String,Parser,Object,Type,Type...)
    • ConfigFile.getObjectWithDefault(String,Object,Class)
    • ConfigFile.getObjectWithDefault(String,Parser,Object,Class)
  • New ability to interact with config file sections with proxy interfaces with new method ConfigFile.getSectionAsInterface(String,Class).
  • @BeanProperty annotation can now be applied to getters and setters defined on interfaces.
  • New methods on SerializerSession and ParserSession for retrieving context and runtime-override properties:
    • Session.getProperty(String)
    • Session.getProperty(String,String)
    • Session.getProperty(Class,String)
    • Session.getProperty(Class,String,Object)
  • New org.apache.juneau.serializer.PartSerializer interface particularly tailored to HTTP headers, query parameters, form-data parameters, and path variables.
    Allows easy user-defined serialization of these objects.
    The interface can be used in the following locations:
    • org.apache.juneau.rest.client.RestClientBuilder.partSerializer(Class)
    • org.apache.juneau.remoteable.Path.serializer
    • org.apache.juneau.remoteable.Query.serializer
    • org.apache.juneau.remoteable.QueryIfNE.serializer
    • org.apache.juneau.remoteable.FormData.serializer
    • org.apache.juneau.remoteable.FormDataIfNE.serializer
    • org.apache.juneau.remoteable.Header.serializer
    • org.apache.juneau.remoteable.HeaderIfNE.serializer
  • Across-the-board improvements to the URI-resolution support (i.e. how URIs get serialized).
    • New support for resolving URIs with the following newly-recognized protocols:
      • "context:/..." - Relative to context-root of the application.
      • "servlet:/..." - Relative to the servlet URI.
      • "request:/..." - Relative to the request URI.
      For example, currently we define HTML page links using variables and servlet-relative URIs...

      pages="{up:'$R{requestParentURI}', options:'?method=OPTIONS', upload:'upload'}"

      With these new protocols, we can define them like so:

      links="{top:'context:/', up:'request:/..' ,options:'servlet:/?method=OPTIONS', upload:'servlet:/upload'}"

      The old method of using variables and servlet-relative URIs will still be supported, but using these new protocols should (hopefully) be easier to understand.
      These protocols work on all serialized URL and URI objects, as well as classes and properties annotated with @URI.
    • New classes:
    • New configuration properties:
    • SerializerContext.SERIALIZER_uriContext
    • SerializerContext.SERIALIZER_uriRelativity
    • SerializerContext.SERIALIZER_uriResolution
    • SerializerContext.SERIALIZER_maxIndent
  • New annotation property: @BeanProperty(value).
    The following two annotations are considered equivalent:

    @BeanProperty(name="foo") @BeanProperty("foo")

  • Fixed a race condition in ClassMeta.
  • URLENC_paramFormat has been moved to UonSerializer.UON_paramFormat, and the UON/URL-Encoding serializers will now always serialize all values as plain text.
    This means that arrays and maps are converted to simple comma-delimited lists.
  • Listener APIs added to serializers and parsers: juneau-examples-core.import1.pngjuneau-examples-core.import1.png
  • The BeanContext.BEAN_debug flag will now capture parser input and make it available through the ParserSession.getInputAsString() method so that it can be used in the listeners.
  • Significant new functionality introduced to the HTML serializer.
    Lots of new options for customizing the HTML output.
    • New @Html(render) annotation and HtmlRender class that allows you to customize the HTML output and CSS style on bean properties:

      Annotation can be applied to POJO classes and bean properties.
    • Several new properties for customizing parts of the HTML page:
      • HtmlDocSerializerContext.HTMLDOC_title
      • HtmlDocSerializerContext.HTMLDOC_description
      • HtmlDocSerializerContext.HTMLDOC_branding
      • HtmlDocSerializerContext.HTMLDOC_header
      • HtmlDocSerializerContext.HTMLDOC_nav
      • HtmlDocSerializerContext.HTMLDOC_aside
      • HtmlDocSerializerContext.HTMLDOC_footer
      • HtmlDocSerializerContext.HTMLDOC_noResultsMessage
      • HtmlDocSerializerContext.HTMLDOC_cssUrl
      • HtmlDocSerializerContext.HTMLDOC_css
      • HtmlDocSerializerContext.HTMLDOC_template
    • New interface HtmlDocTemplate that allows full control over rendering of HTML produced by HtmlDocSerializer.
  • @NameProperty and @ParentProperty can now be applied to fields.
  • New properties on BeanContext:
  • New annotation property: @BeanProperty(format).
org.apache.juneau.rest
org.apache.juneau.rest.client
  • New org.apache.juneau.remoteable.Path annotation for specifying path variables on remoteable interfaces.
  • New @RequestBean annotation for specifying beans with remoteable annotations defined on properties.
  • The following annotations (and related methods on RestCall) can now take NameValuePairs and beans as input when using "*" as the name.
    org.apache.juneau.remoteable.FormData,org.apache.juneau.remoteable.FormDataIfNE, org.apache.juneau.remoteable.Query,org.apache.juneau.remoteable.QueryIfNE, org.apache.juneau.remoteable.Header,org.apache.juneau.remoteable.HeaderIfNE
org.apache.juneau.microservice
org.apache.juneau.examples.rest
  • Many code enhancements make to examples to reflect new functionality.
  • All pages now render aside comments to help explain what feature they're trying to explain using the new features that allow you to customize various elements of the page.

6.3.1 (Aug 1, 2017)

Juneau 6.3.1 is a minor release.

org.apache.juneau
  • PojoQuery improvements.
  • New RemoteMethod.returns() annotation.
    Allows you to specify whether the remote method returns the HTTP body or status code.
  • Fixed bugs with BeanContext.BEAN_includeProperties and BeanContext.BEAN_excludeProperties settings.
  • New/modified settings in HtmlDocSerializerContext:
    • HTMLDOC_script
    • HTMLDOC_style - Was HTMLDOC_css.
    • HTMLDOC_stylesheet - Was HTMLDOC_cssUrl. Now an array.
  • New ResourceFinder utility class. Allows you to search for resources up the parent hierarchy chain. Also allows you to search for localized resources.
  • Eliminated the following properties from HtmlDocSerializerContext: HTMLDOC_title, HTMLDOC_description, HTMLDOC_description
    See below on changes to simplify HTML headers.
  • Var implementations can now throw exceptions and will be converted to ""{exceptionMessage}" values.
org.apache.juneau.rest
  • New 'light' stylesheet:

    Compared with previous 'devops':

    For those nolstalgic for old times, there's also 'original':
  • Simplified the stylesheets and HTML code.
    For example, the nav links are now an ordered list of elements which makes rendering as as side-bar (for example) easier to do in CSS.
  • Modifications to the following @HtmlDoc annotations:
    • navlinks() - Now an array of strings instead of a JSON object. Simplified syntax.
      For example:

      // Old syntax htmldoc=@HtmlDoc( links="{" + "up:'request:/..'," + "options:'servlet:/?method=OPTIONS'," + "contentTypes:'$W{ContentTypeMenuItem}'," + "styles:'$W{StyleMenuItem}'," + "source:'$C{Source/gitHub}/org/apache/juneau/examples/rest/PetStoreResource.java'" + "}" ) // New syntax htmldoc=@HtmlDoc( navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS", "$W{ContentTypeMenuItem}", "$W{StyleMenuItem}", "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/PetStoreResource.java" } )

      Previous syntax will still work, but you're encouraged to use the simplified syntax.
    • Several annotations are now arrays of strings instead of simple strings. Values are simply concatenated with newlines which makes multi-line values cleaner. Additionally, the "INHERIT" string literal can be used to combine the value with the value defined on the servlet or parent class. Links can also be inserted at specific index positions.
  • Improvements made to the Widget API.
    • You can now add arbitrary CSS and Javascript along with your widgets through new methods:
    • Declaration of widgets moved to @HtmlDoc(widgets) instead of separately on @RestResource and @RestMethod annotations.
    • Widget.getName() now defaults to the simple class name.
      So now you can just refer to the class name: "$W{ContentTypeMenuItem}".
    • Renamed widgets:
      • PoweredByApacheWidget -> PoweredByApache
      • PoweredByJuneauWidget -> PoweredByJuneau
    • New MenuItemWidget can be used as a starting point for creatint pull-down menu items.
    • New ContentTypeMenuItem widget that provides a pull-down menu with hyperlinks for all supported languages for that page:
    • Improved QueryMenuItem widget that provides a pull-down menu of a search/view/order-by/page form:

      Fields are now pre-filled with current query parameters.
    • New ThemeMenuItem widget that provides a pull-down menu with hyperlinks to show the content in the default stylesheets:
  • New/modified annotations on @HtmlDoc:
    • style() - Renamed from css().
    • stylesheet() - Renamed from cssUrl().
      Can now be a comma-delimited list of URLs.
    • script() - Add arbitrary Javascript to page header.
  • Bug fix with @HtmlDoc(nowrap) so that the setting only applies to the data contents, not the whole page.
  • Two convenience methods added to RestRequest:
  • Annotations added:
  • Eliminated the @RestResource(stylesheet) annotation. It's no longer needed now that you can easily specify styles via @Htmldoc.
  • Eliminated the following annotations since they are now redundant with @HtmlDoc(header):
    • title()
    • description()
    • branding()
    Instead, the BasicRestServlet class defines the following default header that can be easily overridden:

    htmldoc=@HtmlDoc( header={ "<h1>$R{resourceTitle}</h1>", "<h2>$R{methodSummary,resourceDescription}</h2>", "<a href='http://juneau.apache.org'><img src='$U{servlet:/htdocs/juneau.png}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/></a>" } )

    Note that the subtitle first tries using the method summary and then the servlet description.
  • New $F variable resolver for resolving the contents of files in the classpath.
    The DockerRegistryResource examples shows how it can be used to pull in a localized file from the classpath to populate the aside section of a page.

    htmldoc=@HtmlDoc( // Pull in aside contents from file. aside="$F{resources/DockerRegistryResourceAside.html}" )

  • New ReaderResource.toCommentStrippedString() method.
  • The bpIncludes() and bpExcludes() annotations on @RestMethod has been replaced with the following:
    • bpi() - Now an array of simplified values instead of LAX JSON.
    • bpx() - Now an array of simplified values instead of LAX JSON.
  • Two new variables added to $R variable: "$R{servletClass}", "$R{servletClassSimple}"
org.apache.juneau.rest.examples
  • Added CONTENT-TYPE and STYLES menu items to most pages.
  • Added improved QUERY menu item to PetStore page.

6.4.0 (Oct 5, 2017)

The major change in this release is the project structure.

The library now consists of the following artifacts found in the Maven group "org.apache.juneau":

CategoryMaven ArtifactsDescriptionPrereqs
Juneau Core juneau-marshall Serializers and parsers for:
  • JSON
  • XML
  • HTML
  • UON
  • URL-Encoding
  • MessagePack
  • SOAP/XML
  • CSV
  • BSON (coming soon)
  • YAML (coming soon)
  • Protobuf (coming soon)
  • Java 6
juneau-marshall-rdf Serializers and parsers for:
  • RDF/XML
  • RDF/XML-Abbrev
  • N-Triple
  • Turtle
  • N3
  • Java 6
  • Apache Jena 2.7.1
juneau-dto Data Transfer Objects for:
  • HTML5
  • Atom
  • Cognos
  • JSON-Schema
  • Swagger 2.0
  • Java 6
juneau-svl Simple Variable Language API
  • Java 6
juneau-config Configuration file API
  • Java 6
Juneau REST juneau-rest-server REST Servlet API
  • Java 6
  • Servlet 3.1
juneau-rest-server-jaxrs Optional JAX-RS support
  • Java 6
  • JAX-RS 2.0
juneau-rest-client REST Client API
  • Java 6
  • Apache HttpClient 4.5
Juneau Microservice juneau-microservice-server REST Microservice Server API
  • Java 8
  • Eclipse Jetty 9.4.3
juneau-microservice-template Developer template project
  • Java 8
  • Eclipse Jetty 9.4.3
Examples juneau-examples-core Core code examples
juneau-examples-rest REST code examples
Juneau All juneau-all Combination of the following:
  • juneau-marshall
  • juneau-dto
  • juneau-svl
  • juneau-config
  • juneau-rest-server
  • juneau-rest-client
  • Java 6
  • Servlet 3.1
  • Apache HttpClient 4.5
juneau-marshall
  • Improvements to swap support.
    • New @Swap annotation.
      Replaces the @Pojo and @BeanProperty(swap) annotations.
    • Support for per-media-type swaps.
      Programmatic example:

      @Swap(MyJsonOnlySwap.class) public class MyPojo {} public class MyJsonOnlySwap extends PojoSwap<MyPojo,String> { public MediaType[] forMediaTypes() { return MediaType.forStrings("*/json"); } public String swap(BeanSession session, MyPojo o) throws Exception { return "It's JSON!"; }


      Annotated example:

      @Swap(impl=ToStringSwap.class, mediaTypes="*/json") public class MyBean { ... } public class ToStringSwap extends PojoSwap<Object,String> { public String swap(BeanSession session, Object o) throws Exception { return o.toString(); } }

    • Support for templated swaps which provide additional context information for a swap.
      The following is an example of a templated swap class used to serialize POJOs to HTML using FreeMarker:

      // Our abstracted templated swap class. public abstract class FreeMarkerSwap extends PojoSwap<Object,Reader> { public MediaType[] forMediaTypes() { return MediaType.forStrings("*/html"); } public Reader swap(BeanSession session, Object o, String template) throws Exception { return getFreeMarkerReader(template, o); // Some method that creates raw HTML. } }

      @Swap(impl=FreeMarkerSwap.class, template="MyPojo.div.ftl") public class MyPojo {}

    • New @Swaps annotation for defining multiple swaps against the same POJO when they're differentiated by media types:

      @Swaps( { @Swap(MyJsonSwap.class), @Swap(MyXmlSwap.class), @Swap(MyOtherSwap.class) } ) public class MyPojo {}

  • New Surrogate interface for identifying surrogate classes.
  • Serializers can now serialize to StringBuilders.
  • Serializers now serialize the contents of Readers and InputStreams directly to the output stream or writer.
    When used with conjunction with PojoSwaps, this can be used to provide customized output for specific content types.

    @Pojo(swap=MyBeanSwap.class) public class MyBean {...} public class MyBeanSwap extends PojoSwap<MyBean,Object> { public Object swap(BeanSession session, MyPojo o) throws Exception { MediaType mt = session.getMediaType(); if (mt.hasSubType("json")) return new StringReader("{foo:'bar'}"); // Custom JSON output return o; // Otherwise treat as normal bean } } // Produces "{foo:'bar'}" String json = SimpleJsonSerializer.DEFAULT .toString(new MyBean());


    This feature helps with the implementation of language-agnostic template support such as for using FreeMaker to serialize POJOs to HTML.
  • SerializerSession and ParserSession objects are now reusable if used within the same thread.

    // Old way (still works) JsonSerializer.DEFAULT.serialize(writer1, pojo1); JsonSerializer.DEFAULT.serialize(writer2, pojo2); // Same, but using a session object SerializerSession session = JsonSerializer.DEFAULT.createSession(); try { session.serialize(writer1, pojo1); session.serialize(writer2, pojo2); } finally { session.close(); }

    This is mostly an internal change and doesn't affect the existing APIs.
  • PojoSwap.swap(BeanSession,Object) and PojoSwap.unswap(BeanSession,Object,ClassMeta) can now throw arbitrary exceptions instead of having to wrap them in SerializeException/ParseException.
  • New CalendarUtils class that encapsulates serialization/parsing logic from CalendarSwap and DateSwap.
  • New annotation Html.anchorText().
  • New methods on ObjectList:
  • New methods on ObjectMap:
  • New methods on PojoRest:
  • Fixed bug where BeanSession.getMediaType() wasn't returning a value.
  • Eliminated the @Consumes and @Produces annotations.
    The supported media types are now passed in through the constructors.
    This was changed to eliminate a performance issue where a field could not be set as final because the call to getClass() to retrieve the annotation value could not be called before calling the super() method.
  • New class: PojoMerge
  • New doc: 2.6.2 - @Pojo annotation
  • New doc: 2.6.5 - Serializing Readers and InputStreams
juneau-dto
  • HtmlElementMixed.children(Object...) can now take in collections of objects.
  • The DTO beans can now be serialized to strings of their typical language by calling the toString() method.
    For example, Swagger.toString() produces JSON and the HTML5 Form.toString() produces HTML.
juneau-rest-server
juneau-microservice
org.apache.juneau.rest.examples
  • New example of adding a menu-item widget to the Pet Store resource (including tooltips):

7.0.0 (Oct 25, 2017)

This release ups the Java prerequisite to Java 7.

juneau-marshall
  • New class HttpMethodName with valid static string HTTP method names.
juneau-dto
  • Class org.apache.juneau.dto.Link renamed to LinkString. Helps avoid confusion since there are other Link classes in the library.
juneau-rest-server
  • Annotation @HtmlDoc(links) renamed to navlinks.
  • New annotation @HtmlDoc(head).
    Allows you to specify arbitrary HTML content in the <head> section of the page.
  • Removed annotation @HtmlDoc(favIcon).
    This was a discouraged way of defining fav-icons anyway, and with the addition of @HtmlDoc(head), you can define them using:

    head={ "<link rel='icon' href='$U{servlet:/htdocs/juneau.png}'/>" }

  • Removed several of the HTMLDOC-related methods from the RestResponse/RestConfig/RestContext classes and moved it into the new HtmlDocBuilder class.

7.0.1 (Dec 24, 2017)

This release is a minor update. It includes the following prereq updates:

  • Apache HttpClient: 4.5.3 to 4.5.4
  • Eclipse Jetty: 9.4.6.v20170531 to 9.4.8.v20171121
juneau-marshall
juneau-svl
juneau-rest-server
juneau-microservice-server
  • New pluggable console commands.
    When you start up the microservice, you'll now see the following:

    Running class 'RestMicroservice' using config file 'examples.cfg'. Server started on port 10000 List of available commands: exit -- Shut down service restart -- Restarts service help -- Commands help echo -- Echo command > help help NAME help -- Commands help SYNOPSIS help [command] DESCRIPTION When called without arguments, prints the descriptions of all available commands. Can also be called with one or more arguments to get detailed information on a command. EXAMPLES List all commands: > help List help on the help command: > help help >

    Commands are pluggable and extensible through the config file.

    #======================================================================================================================= # Console settings #======================================================================================================================= [Console] enabled = true # List of available console commands. # These are classes that implements ConsoleCommand that allow you to submit commands to the microservice via # the console. # When listed here, the implementations must provide a no-arg constructor. # They can also be provided dynamically by overriding the Microservice.createConsoleCommands() method. commands = org.apache.juneau.microservice.console.ExitCommand, org.apache.juneau.microservice.console.RestartCommand, org.apache.juneau.microservice.console.HelpCommand

  • Console input reader and output writer can now be overridden.
  • Console strings are now internationalized.

7.1.0 (Mar 08, 2018)

Version 7.1.0 is a major update with major implementation refactoring across all aspects of the product.

juneau-marshall
juneau-svl
juneau-config
  • The Config API has been completely revamped.
    New features include:
    • Support for pluggable storage.
    • File-system watcher integration support.
      Changes made to file system files now automatically reflected in configurations and interface proxies.
    • New builder-based design.
juneau-dto
  • Enhancements to Swagger DTO:
juneau-rest-server
juneau-rest-client
juneau-microservice

7.2.1 (Sept 25, 2018)

7.2.1 is a major release that introduces several significant new features:

  • OpenAPI part serializing and parsing with full support for OpenAPI validation of input and output in the REST servlet and client APIs.
  • Swagger UI.
  • New HTTP-Part annotations that are applicable to both the servlet and client APIs.
  • Serverless servlet and client unit testing.
  • Simplified UI customization.
  • Marshalls that combines serializers and parsers into a single API.
juneau-marshall
  • The REST client @Remoteable annotations and REST server @RemoteMethod annotations which used to be in separate packages in the client and server projects have been combined into a single set of annotations in the org.apache.juneau.http.annotation package.
    This fixes a long-standing problem where it was easy to mix up using client-side annotations in server-side code, and vis-versa.
    Additionally, much work has been done on these annotations to add support for Swagger-style validations and documentation.
    These are used with new Swagger schema/documentation annotations to produce schema-based serialization/parsing/validation and auto-generated Swagger documentation:
    Additionally, the @Remoteable annotation has been split into the following two annotations:
    • RemoteInterface - Used for remote proxy interfaces served up through RemoteInterfaceServlet or REST "PROXY" methods.
      Defaults to "POST" with method signatures as paths.
    • RemoteResource - Used for 3rd-party REST interfaces.
      Defaults to "GET" with standardized naming conventions for paths.
  • Support for multi-valued parameters as maps or beans on server-side annotations (it was previously supported on client-side): @Query("*"), @FormData("*"), @Header("*"), @Path("*")
  • Support for server-side use of @Request annotation on @RestMethod annotations and new RestRequest.getRequest(RequestBeanMeta) method.
  • Fixed bug where @Bean(typeName) was not being detected on non-bean POJO classes.
  • Fixed bug where HTML-Schema was not being rendered correctly.
  • Support for POJO examples:
  • Fixed bug where parsers could report the wrong line number when an error occurred.
  • A runtime exception is now thrown if you define a @BeanProperty(name) but forget to add it to your @Bean(properties) annotation.
  • @Html(asXml) and @Html(asPlainText) replaced with @Html(format).
  • HTML serializer will now serializers beans and maps as HTML even when those objects are embedded within an object with @Html(format=XML).
    The previous behavior was to serialize it as XML.
  • New settings for binary-based serializers and parsers:
  • Added support for auto-detection of fluent-style setters:
  • The SERIALIZER_abridged setting has been replaced with SERIALIZER_addRootType
  • The SERIALIZER_addBeanTypeProperties setting has been replaced with SERIALIZER_addBeanTypes and is disabled by default.
  • Parse exception messages are now clearer and include code snippets of where a parse exception occurred:

    org.apache.juneau.parser.ParseException: Expected '[' at beginning of JSON array. At line 80, column 20. While parsing into: currentClass: List<String> currentProperty: required: java.util.List, field=[null], getter=[public java.util.List org.apache.juneau.dto.swagger.SchemaInfo.getRequired()], setter=[public org.apache.juneau.dto.swagger.SchemaInfo org.apache.juneau.dto.swagger.SchemaInfo.setRequired(java.util.Collection)] ---start-- 0075: "name": "body", 0076: "description": "Pet object that needs to be added to the store", 0077: "required": true, 0078: "schema": { 0079: "required": true, 0080: } 0081: } 0082: ], 0083: "responses": { 0084: "405": { 0085: "description": "Invalid input" ---end---

  • New property Parser.PARSER_debugOutputLines for controlling how many input lines are added to the exception message above.
  • New property BeanContext.BEAN_useEnumNames for controlling whether enums are serialized using their name or the toString() method.
  • New property BeanContext.BEAN_examples for defining examples of POJOs.
  • New @Example annotation for defining examples of POJOs.
    Used heavily in JSON-Schema support.
  • If a bean has both a getX() and isX() method, the getX() method takes precedence.
    The previous behavior was arbitrary.
  • Significant improvements to JSON-Schema serialization support.
    • New @JsonSchema annotation.
  • Fixed NullPointerException when serializing beans with a dyna-property (i.e. @Bean("*")) which returns a null value.
  • New option for dyna-property (i.e. @Bean("*")) using a method that returns a collection of extra keys.
    See new options #4 on BeanProperty.name()
  • New formats for the @Html(format) annotation:
  • Serializers now allow for q-values on the media types they handle.
    For example, the accept media type on JsonSerializer.Simple is "application/json+simple,application/json;q=0.9".
    This means the serializer CAN handle requests for "application/json" if no other serializers provide a better match.
  • New methods for creating unmodifiable ObjectMaps and ObjectLists.
  • The JsonSerializer.Simple class has been moved into the top-level SimpleJsonSerializer class.
  • RDF serializer subclasses have been moved into top-level classes:
  • New API for pairing serializers and parsers for simplified syntax:
    Examples:

    // Using instance. Json json = new Json(); MyPojo myPojo = json.read(string, MyPojo.class); String string = json.write(myPojo);

    // Using DEFAULT instance. MyPojo myPojo = Json.DEFAULT.read(string, MyPojo.class); String string = Json.DEFAULT.write(myPojo);

  • New/updated documentation:
juneau-dto
  • Fixed bug where Swagger SchemaInfo.required(Object...) was defined as a boolean instead of a list of strings.
  • Boolean attributes are now handled correctly for HTML5.
    For example, calling new Select().disabled(true) will produce <select disabled='disabled'>
juneau-rest-server
juneau-rest-client
juneau-rest-microservice
  • The look-and-feel of an application is now controlled through the external configuration file and access to CSS stylesheets in the working directory in a new folder called files:


    The default configuration is this:

    #======================================================================================================================= # REST settings #======================================================================================================================= [REST] staticFiles = htdocs:files/htdocs # Stylesheet to use for HTML views. theme = servlet:/htdocs/themes/devops.css headerIcon = servlet:/htdocs/images/juneau.png headerLink = http://juneau.apache.org footerIcon = servlet:/htdocs/images/asf.png footerLink = http://www.apache.org icon = $C{REST/headerIcon} header = <a href='$U{$C{REST/headerLink}}'><img src='$U{$C{REST/headerIcon}}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/></a> footer = <a href='$U{$C{REST/footerLink}}'><img style='float:right;padding-right:20px;height:32px' src='$U{$C{REST/footerIcon}}'>



    Note that static files can now be served up from the files directory in the working directory, and you have access to modify the CSS theme files.
    The SwaggerUI.css file controls the look-and-feel of the Swagger UI, so you can make modification there as well.

    The BasicRestConfig interface (which defines the default settings for the BasicRestServlet class) now looks like this...

    @RestResource( ... htmldoc=@HtmlDoc( header={ "<h1>$R{resourceTitle}</h1>", "<h2>$R{methodSummary,resourceDescription}</h2>", "$C{REST/header}" }, navlinks={ "up: request:/.." }, stylesheet="$C{REST/theme,servlet:/htdocs/themes/devops.css}", head={ "<link rel='icon' href='$U{$C{REST/icon}}'/>" }, footer="$C{REST/footer}" ), // 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" staticFiles={"$C{REST/staticFiles}"} ) public interface BasicRestConfig {}



    The PoweredByApache widget which used to serve as a page footer has been eliminated.

    If you're testing out changes in the theme stylesheets, you may want to set the following system property that prevents caching of those files so that you don't need to restart the microservice each time a change is made:

    #======================================================================================================================= # System properties #======================================================================================================================= [SystemProperties] # Disable classpath resource caching. # Useful if you're attached using a debugger and you're modifying classpath resources while running. RestContext.useClasspathResourceCaching.b = false

  • Upgraded to Jetty 9.4.12.

7.2.1 (Oct 23, 2018)

This release contains mostly bug fixes. Code changes have been made to preserve binary backwards compatibility with 7.1.0.

juneau-marshall
  • The @JsonSchema annotation has been merged with the @Schema annotation.
  • Annotations typically used on bean properties (getters/setters/public fields) can now be used on private fields. This is inline with behavior on JPA-annotated beans. These include: @Swap, @Html, @Xml, @BeanProperty.
juneau-rest-server
  • Method-level annotations (e.g. @RestMethod) and parameter-level annotations (e.g. @Query) are now inheritable from parent classes and interfaces.
    This allows you to define Overview > juneau-rest-client > REST Proxies > Dual-purpose (end-to-end) interfaces.
  • The ReaderResource and StreamResource classes have been moved to the org.apache.juneau.http package in juneau-marshall. This allows them to be used as return types in remote REST interfaces.
    A new ResolvingReaderResource class has been added that includes the variable-resolving support since this relies on the juneau-svl package.
  • The RemoteInterfaceServlet class has been renamed to RrpcServlet.
  • @RestMethod(name="PROXY") has been changed to @RestMethod(name="RRPC").
juneau-rest-client
  • The RestClient.getRemoteInterface() method has been renamed to RestClient.getRrpcInterface(Class).
  • Fixed a bug where @RemoteMethod(path) values containing '/' characters were erroneously being encoded.
Skip navigation links

Copyright © 2018 Apache. All rights reserved.