See: Description
Apache Juneau™ is a single cohesive Java ecosystem consisting of the following parts:
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.
Apache Juneau™ is a single cohesive Java ecosystem consisting of the following parts:
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.
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
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"
:
Category | Maven Artifacts | Description | Prereqs |
---|---|---|---|
juneau-core | juneau-marshall | Serializers and parsers for:
|
|
juneau-marshall-rdf |
Serializers and parsers for:
|
|
|
juneau-dto |
Data Transfer Objects for:
|
|
|
juneau-svl | Simple Variable Language API |
|
|
juneau-config | Configuration file API |
|
|
juneau-rest | juneau-rest-server | REST Servlet API |
|
juneau-rest-server-springboot | Spring Boot integration support |
|
|
juneau-rest-server-jaxrs | JAX-RS support |
|
|
juneau-rest-client | REST Client API |
|
|
juneau-microservice | juneau-microservice-core | Microservice API |
|
juneau-microservice-jetty | Jetty Microservice API |
|
|
my-jetty-microservice | Developer template project for Jetty-based microservices. |
|
|
my-springboot-microservice | Developer template project for Spring-Boot-based microservices. |
|
|
juneau-examples | juneau-examples-core | Core code examples | |
juneau-examples-rest | REST code examples | ||
juneau-examples-rest-jetty | REST code examples deployed using Jetty | ||
juneau-examples-rest-springboot | REST code examples deployed using Spring Boot | ||
juneau-all | juneau-all |
Combination of the following:
|
|
The current version of Juneau is 8.0.0
.
The easiest way to pull in the library is through the following maven dependency:
If you would like to work with the bleeding-edge code, you can access the 8.0.1
version through the following repository:
Each of the components are also packaged as stand-alone OSGi modules.
juneau-marshall-8.0.0.jar
org.apache.juneau.marshall_8.0.0.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.
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:
In addition to the default serializers, customized serializers can be created using various built-in options:
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:
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:
The parsers can also be used to populating existing bean and collection objects:
The class hierarchy for the parsers (excluding specialized subclasses) are:
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:
Marshalls exist for all supported languages:
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.
The class hierarchy for the part serializers are:
HttpPartSerializer
SimplePartSerializer
- Serializes directly to strings.
UonSerializer
- Serializes to UON notation.
OpenApiSerializer
- Serializes using Open-API schema rules.
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.
The class hierarchy for the part serializers are:
HttpPartParser
SimplePartParser
- Parses directly from strings.
UonParser
- Parses from UON notation.
OpenApiParser
- Parses using Open-API schema rules.
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
.
Configurable settings can also be set declaratively. The following produces the same serializer.
WriterSerializer s = JsonSerializer
.
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:
For performance reasons, serializers and parsers are immutable.
However, they can be 'copied' and modified using the builder()
method.
All serializers and parsers extend from the BeanContext
class.
Therefore, the following properties are common to all serializers and parsers:
BeanContext
BEAN_beanClassVisibility
BEAN_beanConstructorVisibility
BEAN_beanDictionary
BEAN_beanFieldVisibility
BEAN_beanFilters
BEAN_beanMapPutReturnsOldValue
BEAN_beanMethodVisibility
BEAN_beansRequireDefaultConstructor
BEAN_beansRequireSerializable
BEAN_beansRequireSettersForGetters
BEAN_beansRequireSomeProperties
BEAN_beanTypePropertyName
BEAN_debug
BEAN_examples
BEAN_excludeProperties
BEAN_fluentSetters
BEAN_ignoreInvocationExceptionsOnGetters
BEAN_ignoreInvocationExceptionsOnSetters
BEAN_ignorePropertiesWithoutSetters
BEAN_ignoreUnknownBeanProperties
BEAN_ignoreUnknownNullBeanProperties
BEAN_implClasses
BEAN_includeProperties
BEAN_locale
BEAN_mediaType
BEAN_notBeanClasses
BEAN_notBeanPackages
BEAN_pojoSwaps
BEAN_propertyNamer
BEAN_sortProperties
BEAN_timeZone
BEAN_useEnumNames
BEAN_useInterfaceProxies
BEAN_useJavaBeanIntrospector
In addition to the common properties above, the following properties are common to all serializers:
BeanTraverseContext
BEANTRAVERSE_detectRecursions
BEANTRAVERSE_ignoreRecursions
BEANTRAVERSE_initialDepth
BEANTRAVERSE_maxDepth
Serializer
SERIALIZER_addBeanTypes
SERIALIZER_addRootType
SERIALIZER_listener
SERIALIZER_sortCollections
SERIALIZER_sortMaps
SERIALIZER_trimEmptyCollections
SERIALIZER_trimEmptyMaps
SERIALIZER_trimNullProperties
SERIALIZER_trimStrings
SERIALIZER_uriContext
SERIALIZER_uriRelativity
SERIALIZER_uriResolution
SERIALIZER_useWhitespace
WriterSerializer
OutputStreamSerializer
In addition to the common properties above, the following properties are common to all parsers:
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
These object can be serialized in one of two ways:
ObjectMap.serializeTo(java.io.Writer)
or
ObjectList.serializeTo(java.io.Writer)
methods.
Serializer
serialize methods.
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')
The ObjectMap
and ObjectList
classes have many convenience features:
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...
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.
All the serializers, parsers, and REST server/client classes use the following design pattern:
BeanContext
, JsonSerializer
Context
objects.
BeanSession
, JsonSerializerSession
Sessions
but lighter than Contexts
.
Context
contains one PropertyStore
that defines all the configuration about that object.
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
The class hierarchy for JsonSerializerBuilder
is:
Object
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:
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
.
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.
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.
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:
The swap can then be associated with serializers and parsers like so:
The BeanMap.get(Object)
and BeanMap.put(String,Object)
methods will automatically convert to swapped values as the following example shows:
Another example of a PojoSwap
is one that converts
arrays to
BASE64-encoded strings:
The following example shows the BASE64 swap in use:
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.
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.
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:
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.
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.
@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.
Multiple swaps can be associated with a POJO by using the @Swaps
annotation:
Readers
get serialized directly to the output of a serializer.
Therefore it's possible to implement a swap that provides fully-customized output.
The
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:
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:
The implementation of the FreeMarker swap would look something like this:
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.
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:
fromString(String)
- UUID
valueOf(String)
- Boolean
, Byte
,
Double
, Float
,
Integer
, Long
, Short
, Date
,
Time
, Timestamp
parse(String)
- DateFormat
, MessageFormat
,
NumberFormat
, Date
, Level
parseString(String)
- DatatypeConverter
forName(String)
- Class
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.
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:
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):
This could be solved with the following PojoSwap
.
However, the same can be accomplished by using a surrogate class that simply contains a constructor with the non-serializable class as an argument:
The surrogate class is registered in the same way as a PojoSwap
:
When the serializer encounters the non-serializable class, it will serialize an instance of the surrogate instead.
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.
Bean properties can be excluded using the @Bean(excludeProperties)
annotation.
Bean properties can be sorted alphabetically using @Bean(sort)
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.
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.
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
.
The @Bean(propertyFilter)
annotation
and PropertyFilter
class can be used to perform interception
and inline handling of bean getter and setter calls.
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.
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.
The bean property named
The following shows various ways of using dynamic bean properties.
Similar rules apply for value types and swaps. The property values optionally can be any serializable type or use swaps.
BeanContext.BEAN_ignoreUnknownBeanProperties
setting to ignore values
that don't fit into existing properties.
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:
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.
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.
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:
The @BeanProperty(format)
annotation specifies a String format for converting a bean property value to a formatted string.
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:
Beans can also be defined with a combination of read-only and read-write properties.
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.
When applied to fields and getters/setters, they will be ignored as bean properties.
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.
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.
Parsers will automatically set this field for you in the child beans.
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.
The code for such a builder is shown below:
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:
The first can be accomplished through any of the following:
create()
method on the POJO class that returns a builder instance.
Builder
interface.
@Builder
annotation on the POJO class.
The second can be accomplished through any of the following:
build()
method on the builder 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:
The programmatic equivalent would be:
Bean filters are added to serializers and parsers using the following:
For example:
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.
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:
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:
When serialized, the serialized bean will only include properties defined on the interface.
WriterSerializer s = JsonSerializer
.
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.
to the serializer, like so:
WriterSerializer s = JsonSerializer
.
The annotation equivalent is Bean#interfaceClass()
.
The annotation can be used in a couple of ways.
Using the annotation on an interface will be inherited by all children.
The annotation can be used on parent classes as well. Child beans will only serialize properties defined on the parent class.
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
.
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.
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:
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
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
When serialized as JSON,
{
x: [
{_type:
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:
Bean dictionaries are registered through the following:
BeanProperty(beanDictionary)
- On individual bean properties through the annotation.
Bean(beanDictionary)
- On all properties on a bean and all subclasses.
BeanContext.BEAN_beanDictionary
- Configuration property on serializers and parsers.
BeanContextBuilder.beanDictionary(Object...)
- Builder method on serializers and parsers.
The bean dictionary setting can consist of any of the following types:
@Bean(typeName)
.
BeanDictionaryList
containing a collection of bean classes with type name annotations.
BeanDictionaryMap
containing a mapping of type names to classes without type name annotations.
The
Bean(typePropertyName)
- On individual beans through the annotation.
BeanContext.BEAN_beanTypePropertyName
- Configuration property on serializers and parsers.
BeanContextBuilder.beanTypePropertyName(String)
- Builder method on serializers and parsers.
When using the annotation, you'll typically want to define it on an interface class so that it can be inherited by all subclasses.
object, array, number, boolean, null
.
Serializer.SERIALIZER_addBeanTypes
configuration property.
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:
In the following example, the abstract class has two subclasses:
When serialized, the subtype is serialized as a virtual
JsonSerializer s = SimpleJsonSerializer.
The following shows what happens when parsing back into the original object.
JsonParser p = JsonParser.
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:
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.
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:
Now we create a model with a loop and serialize the results.
What we end up with is the following, which does not serialize the contents of the c
field:
{
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.
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:
We can parse this into a generic ObjectMap
:
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:
Once parsed into a generic model, various convenience methods are provided on the ObjectMap
and ObjectList
classes to retrieve values:
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.
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.
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.
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.
URI resolution is controlled by the following settings:
Serializer.SERIALIZER_uriContext
Serializer.SERIALIZER_uriRelativity
UriRelativity.RESOURCE
UriRelativity.PATH_INFO
Serializer.SERIALIZER_uriResolution
UriResolution.ABSOLUTE
UriResolution.ROOT_RELATIVE
UriResolution.NONE
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:
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:
Jackson | Juneau |
---|---|
|
@BeanProperty
|
|
@BeanProperty(name="*")
|
|
@BeanIgnore
|
|
@Bean(excludeProperties="...")
|
|
No equivalent annotation, but can be controlled via:
BeanContext.BEAN_beanFieldVisibility
BeanContext.BEAN_beanMethodVisibility
Future annotation support planned. |
|
@BeanConstructor
|
No equivalent.
Future support planned. |
|
|
Juneau uses swaps to convert non-serializable object to serializable forms:
@Swap
|
No equivalent annotation, but can be controlled via various settings:
BeanContext
Serializer
Future annotation support planned. |
|
@Bean(properties="...")
@Bean(sort=x)
|
|
|
Can be replicated using swaps with Reader swapped values.
|
The following chart shows POJOs categorized into groups and whether they can be serialized or parsed:
Group | Description | Examples | Can serialize? | Can parse? |
---|---|---|---|---|
1 | Java primitives and primitive objects |
|
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. |
|
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. |
|
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 .
|
|
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 .
|
|
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. |
|
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:
|
|
yes | yes |
6b |
Classes that only have a method to convert to a serializable form:
|
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 |
detectRecursions
to look for and handle these kinds of loops
(by setting these references to A separate category exists for POJOs that can be converted to and from Strings. These are used in places such as:
As a general rule, all POJOs are converted to Strings using the toString()
method.
However, there is one exception:
TimeZone
- Uses TimeZone.getID()
POJOs are convertible from Strings using any of the following (matched in the specified order):
create(String)
fromString(String)
fromValue(String)
valueOf(String)
parse(String)
parseString(String)
forName(String)
forString(String)
String
.
Exceptions exist for the following classes:
TimeZone
- Uses TimeZone.getTimeZone(String)
Locale
- Uses Locale.forLanguageTag(String)
after replacing Boolean
- Blank and void .class
) - Uses the primitive wrapper classes for instantiating from Strings.
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):
create(X)
from*(X)
X
.
to*()
.
POJOs are considered convertible from X if any of the reverse of above are true.
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:
Person p =
{
{
name:
The JSON data type produced depends on the Java object type being serialized.
POJO type | JSON type | Example | Serialized form |
---|---|---|---|
String | String | serialize( |
|
Number | Number | serialize(123); |
123
|
Boolean | Boolean | serialize( |
|
Null | Null | serialize( |
|
Beans with properties of any type on this list | Object | serialize( |
{p1:
|
Maps with values of any type on this list | Object | serialize( |
{key1:
|
Collections and arrays of any type on this list | Array | serialize( |
[1,
|
In addition, swaps can be used to convert non-serializable POJOs into serializable forms, such as converting
Calendar
object to ISO8601 strings, or
arrays to Base-64
encoded strings.
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:
The SimpleJsonSerializer
class can be used to serialized POJOs into Simplified JSON notation.
Simplified JSON is identical to JSON except for the following:
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.
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:
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.
The following shows the JSON representation with and without the annotation present:
Without annotation | With annotation |
---|---|
{
|
{
|
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.
The code for creating our POJO model and generating JSON-Schema is shown below:
{
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:
Person p =
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.
The following examples show how different data types are represented in XML. They mirror how the data structures are represented in JSON.
The representation of loose (not a direct bean property value) simple types are shown below:
Data type | JSON example | XML |
---|---|---|
string | ||
boolean | ||
integer | 123 | |
float | 1.23 | |
null |
Loose maps and beans use the element
Object
or superclass/interface value type).
Data type | JSON example | XML |
---|---|---|
Map<String,String> |
{
k1: |
|
Map<String,Number> |
{
k1: 123,
k2: 1.23,
k3: |
|
Map<String,Object> |
{
k1: |
Loose collections and arrays use the element
Data type | JSON example | XML |
---|---|---|
String[] |
[
|
|
Number[] |
[
123,
1.23,
|
|
Object[] |
[
|
|
String[][] |
[
[ |
|
|
[ 123 ] | |
|
[
|
|
List<String> |
[
|
|
List<Number> |
[
123,
1.23,
|
|
List<Object> |
[
|
Data type | JSON example | XML |
---|---|---|
|
{
|
Data type | JSON example | XML |
---|---|---|
|
{
|
The XmlSerializer
class is used to serialize POJOs into XML.
The XmlDocSerializer
class is the same, but serializes a
The XML serializers provide the following settings:
The following pre-configured serializers are provided for convenience:
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:
The @Bean(typeName)
annotation can be used to
override the Juneau default name on bean elements.
Types names serve two distinct purposes:
Data type | JSON example | Without annotation | With annotation |
---|---|---|---|
|
{
a: |
On bean properties, a
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.
Java | Without annotation | With annotation |
---|---|---|
|
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
Java | XML |
---|---|
|
|
|
|
|
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 |
---|---|
|
|
|
|
|
|
|
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
Java | XML |
---|---|
|
|
|
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.
The @Xml(childName)
annotation can be used to
specify the name of XML child elements for bean properties of type collection or array.
Data type | JSON example | Without annotation | With annotation |
---|---|---|---|
|
{
a: [ |
||
|
{ a: [123,456] } |
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).
Data type | JSON example | Without annotation | With annotation |
---|---|---|---|
|
{
a: |
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.
Data type | JSON example | Without annotation | With annotation |
---|---|---|---|
|
{
a: |
The XmlFormat.ELEMENT
format can be applied to bean properties
to override the XmlFormat.ATTRS
format applied on the bean
class.
Data type | JSON example | Without annotation | With annotation |
---|---|---|---|
|
{
a: |
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.
Data type | JSON example | Without annotation | With annotation |
---|---|---|---|
|
{
|
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 |
---|---|---|---|
|
{
a: [ |
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 |
---|---|---|
|
{
a: |
|
|
{
a: |
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 |
---|---|---|---|
|
{
a: [
|
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,
The examples below show how whitespace is handled under various circumstances:
Data type | XML |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
It should be noted that when using
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 |
---|---|---|---|
|
{
a: |
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 |
---|---|---|---|
|
{
a: |
Let's go back to the example of our original Person
bean class, but add some namespace annotations:
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:
Person p =
Now when we run this code, we'll see namespaces added to our output:
Enabling the XmlSerializer.XML_addNamespaceUrisToRoot
setting results
in the namespace URLs being added to the root node:
We can simplify the output by setting the default namespace on the serializer so that all the elements do not need to be prefixed:
This produces the following equivalent where the elements don't need prefixes since they're already in the default document namespace:
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.
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 (
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.
The code for creating our POJO model and generating XML Schema is shown below:
Now if we add in some namespaces, we'll see how multiple namespaces are handled.
The schema consists of 4 documents separated by a
For convenience, the #getValidator(SerializerSession,Object)
method is provided to create a
Validator
using the input from the serialize method.
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.
The following examples show how different data types are represented in HTML. They mirror how the data structures are represented in JSON.
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 | ||
boolean | ||
integer | 123 | |
float | 1.23 | |
null |
Maps and beans are represented as tables.
The
Data type | JSON example | HTML |
---|---|---|
Map<String,String> |
{
k1: |
|
Map<String,Number> |
{
k1: 123,
k2: 1.23,
k3: |
|
Map<String,Object> |
{
k1: |
Collections and arrays are represented as ordered lists.
Data type | JSON example | HTML |
---|---|---|
String[] |
[
|
|
Number[] |
[
123,
1.23,
|
|
Object[] |
[
|
|
String[][] |
[
[ |
|
|
[ 123 ] | |
|
[
|
Data type | JSON example | HTML |
---|---|---|
List<String> |
[
|
|
List<Number> |
[
123,
1.23,
|
|
List<Object> |
[
|
Data type | JSON example | HTML |
---|---|---|
|
{
|
Data type | JSON example | HTML |
---|---|---|
|
{
|
The HtmlSerializer
class is used to serialize POJOs into HTML.
The HtmlDocSerializer
class is the same, but wraps the serialized POJO
inside a document template consisting of header, nav, aside, and footer sections.
The HTML serializers provides the following settings:
The following pre-configured serializers are provided for convenience:
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:
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.
The @Html(anchorText)
annotation is used to specify the anchor text of a hyperlink.
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=
so that
the beans get serialized as standard XML:
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
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:
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.
The HTMLDOC_template
setting defines
a template for the HTML page being generated.
The default template is described next.
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:
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.
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.
The code for creating our POJO model and generating HTML-Schema is shown below:
The result is the HTML table shown below:
type | object | ||||||||||||||||||||||||||||||||||||||||||
properties |
|
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:
Person p =
(
Java type | JSON equivalent | UON |
---|---|---|
Maps/beans | OBJECT |
|
Collections/arrays | ARRAY |
|
Booleans | BOOLEAN |
|
int/float/double/... | NUMBER |
|
null | NULL |
|
String | STRING |
|
Refer to the UON specification for a complete set of syntax rules.
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:
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:
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:
Person p =
Java type | JSON equivalent | UON |
---|---|---|
Maps/beans | OBJECT |
|
Collections/arrays | ARRAY |
|
Booleans | BOOLEAN |
|
int/float/double/... | NUMBER |
|
null | NULL |
|
String | STRING |
|
Refer to the UON specification for a complete set of syntax rules.
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:
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:
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.
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.
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:
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:
Juneau supports converting arbitrary POJOs to and from strings using OpenAPI-based schema rules.
The relevant classes for using OpenAPI-based serialization are:
OpenApiSerializer
- Converts POJOs to strings.
OpenApiParser
- Converts strings to POJOs.
HttpPartSchema
- Defines the schema for your POJO.
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:
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
:
Type | Format | Intermediate Java Type |
---|---|---|
string or empty |
byte |
|
date |
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.
This example shows how that POJO can be converted to a BASE64-encoded string.
In addition to defining format, the schema also allows for validations of the serialized form.
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.
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.
Under-the-covers, this gets converted to the following schema object:
The following code shows how the schema above can be used to create our pipe+csv list of numbers:
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:
Type | Format | Valid parameter types |
---|---|---|
string or empty |
byte |
|
date |
||
uon |
|
|
empty | ||
boolean |
empty | |
integer |
int32 |
|
int64 |
||
number |
float |
|
double |
||
array |
empty |
|
uon |
|
|
object |
empty |
|
uon |
|
For arrays, an example of "Any POJO transformable to arrays of the default types" is:
In the example above, our POJO class can be used to create our pipe-delimited list of comma-delimited numbers:
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.
We define the following schema:
Then we serialize our bean:
HttpPartSerializer s = OpenApiSerializer.
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:
For this bean, we define the following schema:
HttpPartSchema ps =
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) )
SerializeExceptions
if you attempt an impossible conversion.
(e.g. trying to serialize the string "foo" as a boolean).
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.
The following code shows how the schema above can be used to parse our input into a POJO:
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:
Type | Format | Valid parameter types |
---|---|---|
string or empty |
byte |
|
date |
|
|
uon |
|
|
empty | ||
boolean |
empty | |
integer |
int32 |
|
int64 |
||
number |
float |
|
double |
||
array |
empty |
|
uon |
|
|
object |
empty |
|
uon |
|
For arrays, an example of "Any POJO transformable from arrays of the default types" is:
In the example above, our POJO class can be constructed from our pipe-delimited list of comma-delimited numbers:
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.
We define the following schema again:
Then we parse our input into our POJO:
String input =
Note that serializing into generic Object
properties would have produced similar results:
We can also parse into Maps as well:
String input =
ParseExceptions
if you attempt an impossible conversion.
(e.g. trying to parse the string "foo" into a boolean).
BEANTRAVERSE_detectRecursions
option on the Serializer
class can cause a performance penalty of
around 20%.
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.
juneau-marshall-rdf-8.0.0.jar
org.apache.juneau.marshall.rdf_8.0.0.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:
Juneau supports serializing and parsing arbitrary POJOs to and from the following RDF formats:
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.
The RdfSerializer
class is the top-level class for all Jena-based serializers.
Language-specific serializers are defined as inner subclasses of the RdfSerializer
class:
RdfCommon
RDF_arp_embedding
RDF_arp_err_
RDF_arp_errorMode
RDF_arp_ign_
RDF_arp_iriRules
RDF_arp_warn_
RDF_collectionFormat
RDF_juneauBpNs
RDF_juneauNs
RDF_language
RDF_looseCollections
RDF_n3_abbrevBaseUri
RDF_n3_indentProperty
RDF_n3_minGap
RDF_n3_objectLists
RDF_n3_propertyColumn
RDF_n3_subjectColumn
RDF_n3_useDoubles
RDF_n3_usePropertySymbols
RDF_n3_useTripleQuotedStrings
RDF_n3_widePropertyLen
RDF_rdfxml_allowBadUris
RDF_rdfxml_attributeQuoteChar
RDF_rdfxml_blockRules
RDF_rdfxml_longId
RDF_rdfxml_relativeUris
RDF_rdfxml_showDoctypeDeclaration
RDF_rdfxml_showXmlDeclaration
RDF_rdfxml_tab
RDF_rdfxml_xmlBase
RDF_useXmlNamespaces
RdfSerializer
The following pre-configured serializers are provided for convenience:
Abbreviated RDF/XML is currently the most widely accepted and readable RDF syntax, so the examples shown here will use that format.
The RdfParser
class is the top-level class for all Jena-based parsers.
Language-specific parsers are defined as inner subclasses of the RdfParser
class:
The RdfParser.Xml
parser handles both regular and abbreviated RDF/XML.
The RDF parser provides the following settings:
RdfCommon
RDF_arp_embedding
RDF_arp_err_
RDF_arp_errorMode
RDF_arp_ign_
RDF_arp_iriRules
RDF_arp_warn_
RDF_collectionFormat
RDF_juneauBpNs
RDF_juneauNs
RDF_language
RDF_looseCollections
RDF_n3_abbrevBaseUri
RDF_n3_indentProperty
RDF_n3_minGap
RDF_n3_objectLists
RDF_n3_propertyColumn
RDF_n3_subjectColumn
RDF_n3_useDoubles
RDF_n3_usePropertySymbols
RDF_n3_useTripleQuotedStrings
RDF_n3_widePropertyLen
RDF_rdfxml_allowBadUris
RDF_rdfxml_attributeQuoteChar
RDF_rdfxml_blockRules
RDF_rdfxml_longId
RDF_rdfxml_relativeUris
RDF_rdfxml_showDoctypeDeclaration
RDF_rdfxml_showXmlDeclaration
RDF_rdfxml_tab
RDF_rdfxml_xmlBase
RDF_useXmlNamespaces
RdfParser
The following pre-configured parsers are provided for convenience:
The @Rdf
annotation
is used to override the behavior of the RDF serializers and parsers on individual bean classes or properties.
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:
In general, the best approach is to define the namespace URIs at the package level using a
package-info.java
class, like so:
This assigns a default prefix of
Now when we rerun the sample code, we'll get the following:
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.
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.
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
We alter our code to pass in values for these new properties.
Now when we run the sample code, we get the following:
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
is already specified).
The following properties would have produced the same output as before.
Note that the
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.
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
Now when we rerun the sample code, we'll see the added root
attribute on the root resource.
XML-Schema data-types can be added to non-String
literals through the
RdfSerializer.RDF_addLiteralTypes
setting.
To enable, set the
Now when we rerun the sample code, we'll see the added root
attribute on the root resource.
juneau-dto-8.0.0.jar
org.apache.juneau.dto_8.0.0.jar
The juneau-dto
library contains several predefined POJOs for generating commonly-used document types.
This section describes support for these POJOs.
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 |
---|---|
|
|
|
|
|
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.
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.
To serialize this to ATOM, use the XmlSerializer
class:
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.
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.
{
This document can be generated by the following Java code:
Methods that take in beans and collections of beans can also take in JSON representations of those objects.
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
Swagger docs can be parsed back into Swagger beans using the following code:
Swagger swagger = JsonParser.
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:
The BasicRestServlet
class (describe later) shows how this swap is used in the REST interface to
generate the Swagger UI shown above:
juneau-svl-8.0.0.jar
org.apache.juneau.svl_8.0.0.jar
The
Most variables can be recursively nested within the varKey (e.g.
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:
SystemPropertiesVar
- $S{key[,default]}
EnvVariablesVar
- $E{key[,default]}
The following logic variables are also provided:
IfVar
- $IF{arg,then[,else]}
SwitchVar
- $SW{arg,pattern1:then1[,pattern2:then2...]}
CoalesceVar
- $CO{arg1[,arg2...]}
PatternMatchVar
- $PM{arg,pattern}
PatternReplaceVar
- $PR{arg,pattern,replace}
PatternExtractVar
- $PE{arg,pattern,groupIndex}
NotEmptyVar
- $NE{arg}
UpperCaseVar
- $UC{arg}
LowerCaseVar
- $LC{arg}
LenVar
- $LN{arg[,delimiter]}
SubstringVar
- $ST{arg,start[,end]}
The following shows how variables can be arbitrarily nested...
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.
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:
Module | Class | Pattern |
---|---|---|
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} | |
PatternReplaceVar |
$PR{arg,pattern,replace} | |
PatternExtractVar |
$PE{arg,pattern,groupdIndex} | |
NotEmptyVar |
$NE{arg} | |
UpperCaseVar |
$UC{arg} | |
LowerCaseVar |
$LC{arg} | |
LenVar |
$LN{arg[,delimiter]} | |
SubstringVar |
$ST{arg,start[,end]} | |
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} |
The main class for performing variable resolution is VarResolver
.
Two methods are provided for resolving variables:
VarResolver
resolve(String)
- Resolves variables and returns the results as a simple string.
resolveTo(String,Writer)
- Resolves variables and sends results to a writer.
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:
The following two classes are identical in behavior except for which objects they can access:
VarResolver
- Has access to context objects only.
VarResolverSession
- Has access to context and session objects.
Context and session objects are set through the following methods:
VarResolverBuilder.contextObject(String,Object)
- Context objects.
VarResolverSession.sessionObject(String,Object)
- Session objects.
VarResolver.createSession(Map)
- Session objects.
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.
$ , { }
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!
resolver.resolve("foobar" )
) will simply be a no-op and return the same string.
juneau-config-8.0.0.jar
org.apache.juneau.config_8.0.0.jar
The juneau-config
library contains a powerful API for creating and using INI-style config files.
Config files are access through the Config
class which
are created through the ConfigBuilder
class.
Builder creator methods are provided on the Config
class:
Once instantiated, reading values from the config are simple:
The config language may look simple, but it is a very powerful feature with many capabilities including:
/ \ [ ] = #
Configuration files can contain entries for anything from primitive types up to complex hierarchies of POJOs consisting of maps, collections, and/or beans.
The most common case for configuration values are primitives.
The following methods are provided for accessing primitive values:
On integers and longs,
Numbers can also use hexadecimal and octal notation:
Strings with newlines are treated as multi-line values that get broken into separate lines:
Typically, multi-line values are started on the next line for clarity like so:
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:
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:
Beans are represented as Simplified JSON by default:
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:
The following methods are provided for accessing arrays:
The getStringArray()
methods allow you to retrieve comma-delimited lists of values:
String[] key1 = c.getStringArray(
String arrays can also be represented in JSON when using the getObject()
methods:
String[] key1 = c.getObject(
Primitive arrays can also be retrieved using the getObject()
methods:
Arrays of POJOs can also be retrieved using the getObject()
methods:
Address[] addresses = c.getObject(
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 )
List<?>
getObject("..." , LinkedList.class )
LinkedList<?>
getObject("..." , HashSet.class , Integer.class )
HashSet<Integer>
getObject("..." , Map.class )
Map<?,?>
getObject("..." , HashMap.class )
HashMap<?,?>
getObject("..." , LinkedHashMap.class , String.class , MyBean.class )
LinkedHashMap<String,MyBean>
getObject("..." , HashMap.class , Integer.class , ArrayList.class , MyBean[].class )
LinkedHashMap<Integer,ArrayList<MyBean[]>>
List<Address> addresses = c.getObject(
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(
The following methods are provided for accessing binary data:
Binary data can be represented in 3 formats:
"Zm9vYmFycw=="
"666F6F62617273"
"66 6F 6F 62 61 72 73"
The binary data format is controlled via the following setting:
For example:
Binary lines can be split up into separate lines for readability:
Binary data line wrapping can be controlled via the following setting:
Config files can contain variables that get resolved dynamically using the previously-described VarResolver
API.
Config c = Config.
By default, Configs
use the VarResolver.DEFAULT
variable resolver
which provides support for the following variables and constructs:
SystemPropertiesVar
- $S{key[,default]}
EnvVariablesVar
- $E{key[,default]}
ConfigVar
- $C{key[,default]}
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:
The default variable resolver also provides the following logic variables for performing simple logical operations:
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}
The $IF
variable can be used for simple if/else logic:
The $SW
variable can be used for switch blocks based on pattern matching:
The $CO
variable can be used for coalescing of values (finding the first non-null/empty match):
The $PM
variable can be used for calculating boolean values:
Encoded entries allow for sensitive information such as passwords to be obfuscated.
Encoded entries are denoted with a
For example, the following password is marked for encoding:
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()
.
Config sections can be retrieved in-bulk using
Config.getSectionAsMap(String)
.
Maps created this way are snapshot copies of the section at the time of the method call.
Config files can also be used to directly populate beans using
Config.getSectionAsBean(String,Class,boolean)
.
Like maps, beans created this way are snapshot copies of the section at the time of the method call.
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.
The following methods allow you to add, remove, and modify entries and sections in a config file:
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.
The last 4 arguments in Config.set(String,Object,Serializer,ConfigMod[],String,List)
are optional in that if you pass
Sections can be added with optional pre-lines using the setSection
methods:
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.
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).
Setter methods that take in a Serializer
can be used to provide custom serialization of entries
instead of using the predefined serializer.
The value can then be retrieved using the equivalent parser:
Address myAddress = c.getObject(
The following methods can be used to bulk-load configuration values:
Changes can then be committed using the Config.commit()
method.
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:
Config.commit()
is called.
In both cases, the listener is triggered after the changes have been committed.
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.
Configuration files are stored in entities called Stores.
The methods that need to be implemented on a store are:
ConfigStore
read(String)
- Read a config file.
write(String,String,String)
- Write a config file.
update(String,String)
- Update the contents of a config file.
Read is self-explanatory:
Write is slightly trickier:
The update method is called whenever the stored file gets modified externally:
Two configuration stores are provided by default:
ConfigFileStore
- File-system storage.
ConfigMemoryStore
- In-memory storage.
The store is defined on the Config
object via the following setting:
The default store used is ConfigFileStore.DEFAULT
which defines
the execution directory as the file system directory to store and retrieve files.
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):
The ConfigFileStore
is the typical store used for configuration files.
It provides the following configurable settings:
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:
The purpose of the builder class is to simply set values in the PropertyStore
that's passed to the ConfigStore
:
The ConfigStore
class has the following listener methods:
ConfigStore
register(String,ConfigStoreListener)
- Register a listener on the specified config name.
unregister(String,ConfigStoreListener)
- Unregister a listener on the specified config name.
Note that this is a different listener than ConfigEventListener
.
In this case, we're just listening for changed files:
ConfigStoreListener
ConfigStoreListener.onChange(String)
- Called when file changes. New contents are passed in.
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.
The following settings can be used to create read-only Config
objects:
This causes all methods that make modifications to throw UnsupportedOperationException
.
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.
Each JVM has a system default config. This is a configuration file that serves as the default configuration for the system. It's accessed using the following static methods:
If you do not specify a system default config, one will be automatically searched for. The search is done in the following order:
<jar-name>.cfg
.cfg
. First one matched alphabetically is used.
<jar-name>.cfg
juneau.cfg
default.cfg
Later in the section on REST resources, we describe how to associate configurations with REST resources
using the @RestResource(config)
annotation.
The system default configuration can be referenced with the keyword SYSTEM_DEFAULT
like so:
juneau-rest-server-8.0.0.jar
org.apache.juneau.rest.server_8.0.0.jar
The
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
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.
Many of the examples in this document are pulled directly from
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
Like any servlet, we could define our resource in the
Our servlet code is shown below:
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.
The class hierarchy for the REST servlet class is shown below:
javax.servlet.http.HttpServlet
org.apache.juneau.rest.RestServlet
org.apache.juneau.rest.BasicRestServlet
org.apache.juneau.rest.BasicRestServletGroup
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:
RestContext
- Each resource class instance has one copy that holds all of its configuration.
RestContextBuilder
- Builder for the class above.
REST resources are deployed in one of two ways:
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
public T()
public T(RestContextBuilder)
And even that requirement is relaxed if you implement your own REST resource resolver (described later).
For example:
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.
The RestServlet
class is the entry point for your REST resources.
It extends directly from
When the servlet 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 BasicRestServlet
.
The
RestServlet
extends HttpServlet
init(ServletConfig)
- Can override to provide custom initialization.
service(HttpServletRequest,HttpServletResponse)
- Can override to provide custom request handling.
destroy()
- Can override to provide custom cleanup.
getContext()
- Returns all aspects of the configuration of your resource pulled from all annotations on the class/parent-classes and methods.
log(Level,String,Object...)
- Convenience logging method.
log(Level,Throwable,String,Object...)
- Convenience logging method.
The BasicRestServlet
class is a subclass of RestServlet
preconfigured with the following:
The contents of the class is shown below. You should notice that very little code is being used and everything is configurable through annotations:
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.
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
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.
Child Resources are REST servlets or objects that are linked to parent resources through the
@RestResource(children)
annotation.
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
A HUGE advantage of using child resources is that they do not need to be declared in the JEE
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
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
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.
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:
Or if you want to intercept REST calls:
The hook events can be broken down into two categories:
INIT
- Right before initialization.
POST_INIT
- Right after initialization.
POST_INIT_CHILD_FIRST
- Right after initialization, but run child methods first.
DESTROY
- Right before servlet destroy.
START_CALL
- At the beginning of a REST call.
PRE_CALL
- Right before the POST_CALL
- Right after the END_CALL
- At the end of the REST call after the response has been flushed.
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.
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.
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. |
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
- Settings copied from the annotation during servlet initialization.
RestContextBuilder
- Builder used during servlet initialization.
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:
Warning: The builder class is huge. Through it, you can configure bean/serializer/parser settings, define config files, children, resource finders, info providers, etc...
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.
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).
If name
and path
are both specified, the Java method name can be anything.
Java methods can contain any of the following parameters in any order:
RestRequest
- The request object.
HttpServletRequest
- The superclass of RestRequest
.
RestResponse
- The response object.
HttpServletResponse
- The superclass of RestResponse
.
InputStream
ServletInputStream
Reader
OutputStream
ServletOutputStream
Writer
ResourceBundle
- Client-localized resource bundle.
MessageBundle
- A resource bundle with additional features.
Locale
- Client locale.
RequestHeaders
- API for accessing request headers.
RequestQuery
- API for accessing request query parameters.
RequestFormData
- API for accessing request form data.
RequestPath
- API for accessing path variables.
RequestBody
- API for accessing request body.
HttpMethod
- The method name matched (when using @RestMethod (name="*" )
)
RestLogger
- Logger with additional features.
RestContext
- The resource read-only context.
Parser
- The parser matching the request content type.
ReaderParser
- The reader parser matching the request content type.
InputStreamParser
- The input stream parser matching the request content type.
Swagger
- The auto-generated Swagger doc.
Config
- The external config for the resource.
RequestProperties
- API for modifying request-time configuration properties.
Path
- Variables in matched URL path patterns.
FormData
- Multipart form post parameter values.
HasFormData
- Denotes whether the form data parameter exists.
Query
- Query parameters. Using this prevents the HTTP body from being processed as a URL-Encoded form post.
HasQuery
- Denotes whether the query parameter exists.
Header
- A header value.
Body
- The HTTP content parsed as a POJO.
Method
- The HTTP method name.
Request
- HTTP request parts available through a proxy bean interface.
Response
- HTTP response parts available through a POJO.
ResponseHeader
- HTTP response header.
ResponseStatus
- HTTP response status code.
RestRequest
class.
RestContext.REST_paramResolvers
- For configuring custom parameter types.
The RestRequest
object is an extension of the
There are many useful methods on this object, but the main ones are shown below:
RestRequest
extends HttpServletRequest
getHeaders()
- HTTP request headers.
getQuery()
- Query parameters.
getFormData()
- Form-data parameters.
getBody()
- HTTP request body.
getPathMatch()
- Path match variables.
getLogger()
- Logging.
getInfoProvider()
- Swagger documentation provider.
getSwagger()
- Generated Swagger information.
getConfig()
- External configuration API.
getVarResolverSession()
- String variable resolver.
getMessageBundle()
- Localized messages.
getProperties()
- Configuration properties.
getClasspathReaderResource(String,boolean,MediaType,boolean)
- Various methods for retrieving static files from classpath.
The RestResponse
object is an extension of the
Some important methods on this class are:
RestResponse
extends HttpServletResponse
setOutput(Object)
- Set response output programmatically.
getHtmlDocBuilder()
- Set HTTP page contents programmatically.
getDirectWriter(String)
- Direct access to underlying response writer.
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:
Some important methods on this class are:
RequestBody
getReader()
- Get body as a Reader.
getInputStream()
- Get body as an InputStream.
asType(Class)
- Get body converted to a POJO.
asType(Type,Type...)
- Get body converted to a map or collection of POJOs.
asString()
- Get body as a simple string.
asHex()
- Get body as a hex-encoded string.
asSpacedHex()
- Get body as spaced-hex-encoded string.
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:
Some important methods on this class are:
RequestHeaders
extends TreeMap<String,String[]>
get(String,Class)
- Get header value converted to a POJO.
get(String,Type,Type)
- Get header value converted to a map or collection of POJOs.
getString(String,String)
- Get header value as a simple string.
getInt(String,int)
- Get header value as an integer.
getBoolean(String,boolean)
- Get header value as a boolean.
addDefault(String,Object)
- Programmatically set a default value for a header.
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:
An important distinction between the behavior of this object and
Some important methods on this class are:
RequestQuery
extends LinkedHashMap<String,String[]>
get(String,Class)
- Get query parameter value converted to a POJO.
get(String,Type,Type)
- Get query parameter value converted to a map or collection of POJOs.
getString(String,String)
- Get query parameter value as a simple string.
getInt(String,int)
- Get query parameter value as an integer.
getBoolean(String,boolean)
- Get query parameter value as a boolean.
addDefault(String,Object)
- Programmatically set a default value for a query parameter.
getSearchArgs()
- Returns query parameter search arguments.
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:
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:
RequestFormData
extends LinkedHashMap<String,String[]>
get(String,Class)
- Get form-data parameter values converted to a POJO.
get(String,Type,Type)
- Get form-data parameter value converted to a map or collection of POJOs.
getString(String,String)
- Get form-data parameter value as a simple string.
getInt(String,int)
- Get form-data parameter value as an integer.
getBoolean(String,boolean)
- Get form-data parameter value as a boolean.
addDefault(String,Object)
- Programmatically set a default value for a form-data parameter.
The @RestMethod(path)
annotation allows
you to define URL path patterns to match against.
These patterns can contain variables of the form
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...
By default, path patterns are matched using a best-match heuristic. When overlaps occur, URLs are matched from most-specific to most-general order:
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 RequestPath.getRemainder()
or parameters with the
annotation.
On the other hand, paths that don't end with
The following example shows the distinction.
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
The RequestPath
object is the API for accessing the matched variables
and remainder on the URL path.
Some important methods on this class are:
RequestPath
extends TreeMap<String,String>
get(String,Class)
- Get path match variable converted to a POJO.
get(String,Type,Type)
- Get path match variable converted to a map or collection of POJOs.
getString(String)
- Get patch match variable as a simple string.
getInt(String)
- Get path match variable as an integer.
getBoolean(String)
- Get path match variable as a boolean.
getRemainder()
- Get the path match remainder.
The return type can be any serializable POJO as defined in POJO Categories.
It can also be RestResponse.setOutput(Object)
method.
Out-of-the-box, besides POJOs, the following return types are handled as special cases:
InputStream
RestResponse.getNegotiatedOutputStream()
.
ServletResponseWrapper.setContentType(String)
to set
the Reader
RestResponse.getNegotiatedWriter()
.
ServletResponseWrapper.setContentType(String)
to set
the Streamable
Writable
ZipFileList
This is controlled through the following extensible API:
REST Java methods can generate output in any of the following ways:
Reader
, InputStream
, Streamable
,
Writable
RestResponse.setOutput(Object)
with any of the types above.
Writer
directly by calling
RestResponse.getNegotiatedWriter()
and writing the output yourself.
RestContext.REST_responseHandlers
- For configuring custom response handlers.
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.
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.
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.
The interface for matchers is simple:
Predefined response beans are provided for all standard HTTP responses. These can be used as-is or extended to provide customized HTTP responses.
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:
The SeeOtherRoot
class shows how these predefined beans can be extended.
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).
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.
org.apache.juneau.rest.exception
BadRequest
Conflict
ExpectationFailed
FailedDependency
Forbidden
Gone
HttpVersionNotSupported
InsufficientStorage
InternalServerError
LengthRequired
Locked
LoopDetected
MethodNotAllowed
MisdirectedRequest
NetworkAuthenticationRequired
NotAcceptable
NotExtended
NotFound
NotImplemented
PayloadTooLarge
PreconditionFailed
PreconditionRequired
RangeNotSatisfiable
RequestHeaderFieldsTooLarge
ServiceUnavailable
TooManyRequests
Unauthorized
UnavailableForLegalReasons
UnprocessableEntity
UnsupportedMediaType
UpgradeRequired
UriTooLong
VariantAlsoNegotiates
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.
The org.apache.juneau.rest.helper
package contains several predefined beans to help when constructing
REST interfaces.
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:
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:
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):
The @HtmlLink
annotation can also be useful
for rendering custom hyperlinks:
The LinkString
bean is a predefined
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.
The BeanDescription
class provides a simple view
of a bean and it's properties.
This example renders the following:
The ChildResourceDescriptions
is a convenience bean for generating
a table of child resources.
The BasicRestServletGroup
class uses this to generate router pages:
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:
The SeeOtherRoot
class can be used to redirect to the root URI
of a resource class.
The runtime behavior is the same as the following:
One distinction is that the former defines the description
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.
The following example shows a remote interface:
The requirements for a remote interface method are:
Throwables
.
Throwables with public no-arg or single-arg-string constructors are automatically recreated on the client side when thrown on the server 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:
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.
There are two ways to expose remote interfaces on the server side:
RrpcServlet
.
@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.
The RrpcServlet
class is a simple specialized servlet with an abstract
getServiceMap()
method to define the server-side POJOs:
The
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:
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.
http://localhost:10000/remote/org.apache.juneau.examples.addressbook.IAddressBook
Since AddressBook
extends from LinkedList
, you may notice familiar collections
framework methods listed.
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 =
That produces the following JSON output:
[
{
name:
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 =
If we alter our servlet to allow overloaded GET requests, we can invoke methods using nothing more than a browser...
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(
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.
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. Longs
:
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:
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
:
Or even POJOs that take in arrays of Longs[]
:
Or even POJOs that take in the whole 2-dimensional array:
As you can see, the complexity of possible input types expands significantly. For more information about valid parameter types, see OpenAPI Parsers
Parameters annotated with any of the following are serialized using the registered OpenApiSerializer
and
therefore support OpenAPI syntax and validation:
ResponseHeader
Response
(Accept
must match
For example, the following shows how a pipe-delimited list of comma-delimited numbers (e.g. Longs
:
The following shows the same for a response body:
For more information about the valid parameter types, see OpenAPI Serializers
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:
The @Body
annotation is used to identify POJOs to be used as the body of an HTTP request.
This is functionally equivalent to the following code:
Any of the following types can be used for the parameter or POJO class (matched in the specified order):
Reader
Content-Type
is ignored.
InputStream
Content-Type
is ignored.
Content-Type
is required to identify correct parser.
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.
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.
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) {...}
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. Longs
:
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
Default REST SVL Variables (e.g. "$L{my.localized.variable}") are supported on annotation fields.
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:
This is functionally equivalent to the following code:
The special name Map
or 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. Longs
:
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
Default REST SVL Variables (e.g. "$L{my.localized.variable}") are supported on annotation fields.
@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.
@Query
annotation can be used to retrieve a URL parameter in the URL string without triggering the
servlet to drain the body content.
This annotation can be used to detect the existence of a parameter when it's not set to a particular value.
This is functionally equivalent to the following code:
The parameter type must be either Boolean
.
The following table shows the behavioral differences between
Body content |
|
|
---|---|---|
a=foo |
||
a= |
||
a |
||
b=foo |
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.
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:
This is functionally equivalent to the following code:
The special name Map
or 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. Longs
:
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
Default REST SVL Variables (e.g. "$L{my.localized.variable}") are supported on annotation fields.
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.
This is functionally equivalent to the following code:
The parameter type must be either Boolean
.
The following table shows the behavioral differences between
Query content |
|
|
---|---|---|
?a=foo |
||
?a= |
||
?a |
||
?b=foo |
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:
This is functionally equivalent to the following code:
The special name Map
or 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. Longs
:
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
Default REST SVL Variables (e.g. "$L{my.localized.variable}") are supported on annotation fields.
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:
This is functionally equivalent to the following code:
Note that the path variable name
The special name Map
or 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. Longs
:
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
Default REST SVL Variables (e.g. "$L{my.localized.variable}") are supported on annotation fields.
The @Request
annotation can be applied to a parameter interface type of a
Request
partParser
- Override the part parser.
The example above is identical in behavior to specifying individual annotated parameters on the
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.
For clarity, the
The @Response
annotation is used to identify schema information about an HTTP response.
Response
api
- Free-form Swagger JSON.
code
- HTTP status code.
description
- Description.
example
- Serialized example.
examples
- Serialized examples per media type.
headers
- Swagger about headers added to response.
partSerializer
- Override the part serializer.
schema
- Swagger schema.
value
- Free-form Swagger JSON.
It can be used in the following locations:
When the
When applied to an exception class, this annotation defines Swagger schema and information on non-200 return types.
The following example shows the
Custom exceptions can also extend from one of the predefined HTTP exceptions such as the Unauthorized
exception:
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:
Another example showing how a redirect can be defined:
The
The
The Value
(a placeholder for objects).
In the above example, the
The @ResponseStatus
annotation can be used on
the method of a 200
(the default).
The @ResponseHeader
annotation can be used on
the method of a
The @ResponseBody
annotation can be used on
the method of a
If a toString()
).
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:
The
annotation can be used to define the format of the output using OpenAPI-based rules.
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:
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:
The @ResponseHeader
annotation can be applied to
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:
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:
The @ResponseStatus
annotation annotation can be applied to
This can only be applied to parameters of the Value
class with an Integer
type.
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
Another possibility is to access the form parameters individually:
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.
ServletRequestWrapper.getParameter(String)
method since this will cause the
underlying JEE servlet to parse the HTTP body as a form post.
RestRequest.getBody()
The Juneau framework does not natively support multipart form posts. However, it can be done in conjunction with the Apache Commons File Upload library or through the Servlet 3.0 API directly.
The following is an example that uses the File Upload library to allow files to be uploaded as multipart form posts.
The following shows using the
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 Serializer.getMediaTypeRanges()
method.
Serializers can be associated with REST servlets in the following ways:
RestResource(serializers)
- Annotation on resource Java class.
RestMethod(serializers)
- Annotation on resource Java method.
RestContext.REST_serializers
- Programmatic.
The following are all equivalent ways of defining serializers used by a resource:
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 Parser.getMediaTypes()
method.
Parsers can be associated with REST servlets in the following ways:
RestResource(parsers)
- Annotation on resource Java class.
RestMethod(parsers)
- Annotation on resource Java method.
RestContextBuilder.parsers(Class[])
- Programmatic.
The following are all equivalent ways of defining parsers used by a resource:
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:
RestResource(properties)
RestContextBuilder
- Various methods on the context builder.
The programmatic equivalent to this is:
Properties can also be overridden at the Java method level:
Using the RequestProperties
object:
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:
.
Properties are open-ended and can be used for other purposes. They're made available through the following methods:
RestResource(flags)
- Shorthand for boolean properties.
RestMethod(flags)
- Shorthand for boolean properties.
RestContextProperties
RestMethodProperties
RequestProperties
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:
RestResource(beanFilters)
RestResource(pojoSwaps)
RestMethod(beanFilters)
RestMethod(pojoSwaps)
RestContextBuilder.beanFilters(Object...)
RestContextBuilder.pojoSwaps(Object...)
The programmatic equivalent to this is:
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:
When requested as JSON, it produces the following result:
{
URI resolution is controlled by the following settings:
URIs are resolved by both regular and part serializers.
Guards are classes that control access to REST classes and methods.
Guards are associated with resource classes and methods via the following:
A common use for guards is to only allow admin access to certain Java methods...
A guard failure results in an RestGuard.guard(RestRequest,RestResponse)
and processing the response
yourself.
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.
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:
They can also be defined at the method level:
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.
Juneau defines the following converters out-of-the-box:
RestConverter
Queryable
Traversable
Introspectable
The @RestResource(messages)
annotation is used to associate a resource bundle with a servlet class.
The resource bundle can also be passed into the method by simply specifying a parameter
of type ResourceBundle
or MessageBundle
:
If a resource bundle is shared by multiple servlets, the label and description can be prefixed by the class name:
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.
Juneau defines the following encoders out-of-the-box:
In the previous examples, there were several cases where embedded variables were contained within annotation values:
Variables take the form
Variables are configured on resources via the following API:
The methods involved with variables are:
RestContext.getVarResolver()
RestRequest.getVarResolverSession()
RestRequest.getClasspathReaderResource(String,boolean)
There are two distinct groups of variables:
@RestResource
.
RestContext.getVarResolver()
method returns initialization-time variables only.
@HtmlDoc
.
RestRequest.getVarResolverSession()
method returns initialization and request-time variables.
The following is the default list of supported variables.
Module | Class | Pattern | Initialization 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} |
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:
These properties are then accessible through the Config
class.
Config c = Config.
Configuration files are associated with REST resources through the following:
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
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.
Another common usage is to refer to config properties through
It's even possible to reference request-level variables in your config file if you use
RestRequest.getConfig()
to access the config file:
You can even add resource bundles into the mix:
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.
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
RestContext.getMediaTypeForName(String)
method.
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:
RestResource(clientVersionHeader)
RestContextBuilder.clientVersionHeader(String)
RestMethod(clientVersion)
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
The BasicRestInfoProvider
class is the default implementation of the
RestInfoProvider
interface.
It finds and collects information gathered from the following locations:
The class itself is designed to be extended if you wish to rely mostly on the default behavior, but tweak certain aspects.
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:
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:
Note that to have your resource create Swagger UI, you must either extend from BasicRestServlet
or provide
your own Swagger
object and a SwaggerUI
swap.
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.
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.
{
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:
However, a more typical (and less error-prone) scenario is to define all of your Swagger as annotations:
All annotations support SVL variables, so you could for example
pull localized strings from resource bundles using $L
variables.
A third option is to define your Swagger information in your @RestResource(messages)
resource
bundle using predefined Swagger keywords:
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:
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
The annotation-only approach is shown here:
swagger=
Tags are associated with operations using the @MethodSwagger(tags)
annotation:
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:
The following shows the annotations defined on the GET /pet
operation:
Methods marked as deprecated will show up as deprecated in the Swagger UI:
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
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:
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:
Note that the schema information on the body parameter is automatically detected if not provided.
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:
This value gets converted to an x-examples
attribute in your parameter information:
{
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.
@ResourceSwagger (value)
/@MethodSwagger (value)
).
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.
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.
The Swagger generator uses these to create an x-examples
entry in your generated Swagger:
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:
Examples can be defined via static methods, fields, and annotations on the classes themselves.
Examples can also be specified via generic properties as well using the BeanContext.BEAN_examples
property at either the class or method level.
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:
Note that additional responses can be specified by throwing exceptions annotated with the @Response
annotation such
as this one:
Like input parameters, the Swagger for responses can be define in multiple locations such as:
@Response
annotated classes, methods, and parameters.
@RestResource(swagger)
/ @RestMethod(swagger)
annotations.
The model
select box in the responses can be expanded to show examples:
Examples are provided for any supported Accept
type based on the serializers defined on your
servlet/method.
Examples are pulled from the examples
attribute in the response object of the generated Swagger JSON:
There are several options for defining examples for response bodies:
@Response(example)
annotation.
@Response(examples)
annotation.
@ResourceSwagger (value)
/@MethodSwagger (value)
).
The @Response(example)
annotation can be used on either your
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:
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.
Examples can also be specified via generic properties as well using the BeanContext.BEAN_examples
property at either the class or method level.
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:
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
:
In the Swagger UI, this causes bean definitions to show up in the Models section at the bottom of the page:
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:
{
Note that this does not affect how the information is rendered for that bean in the Swagger UI:
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.
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:
The purpose of these annotation is to populate the HTML document view which by default consists of the following structure:
The outline above is controlled by the HtmlDocTemplate
interface
which can be overridden via the @HtmlDoc(template)
annotation.
The
SVL variables can be used in any of these annotations:
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:
As a result, the following guidelines are recommended:
The Widget
class allows you to add arbitrary HTML, CSS, and Javascript
to HTML pages.
They are registered in the following locations:
HtmlDoc(widgets)
RestContextBuilder.widgets(Class...)
RestContextBuilder.widgets(Widget...)
RestContext.REST_widgets
The
The HTML content returned by the getHtml(RestRequest)
method is added wherever the
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)
):
The
The org.apache.juneau.rest.widget
package contains predefined reusable widgets.
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
Subclasses implement the following two methods:
MenuItemWidget
getLabel(RestRequest)
- The menu item label.
getContent(RestRequest)
- The menu item content.
For example, to render a link that brings up a simple dialog in a div tag:
The HTML content returned by the getHtml(RestRequest)
method is added where the
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
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:
It renders the following popup-box:
QueryMenuItem
is a predefined Widget that returns a menu-item drop-down form for entering search/view/sort arguments.
The variable it resolves is
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:
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. Queryable
class knows how to perform these filters against collections of POJOs.
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
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:
PoweredByJuneau
is a predefined Widget that places a powered-by-Juneau message on a page.
The variable it resolves is
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:
It renders the following image:
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.
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.
The default annotation values use $C
variables to pull in values from an optional
external configuration file such as the one shown below:
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.
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:
The org/apache/juneau/rest/styles/devops.css
.
To provide your own stylesheet, simply override the stylesheet attribute and point to a different file:
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:
The MenuItemWidget
, a
specialized widget for creating pop-up menus.
In the case of
The following annotations are provided for specifying default header values for requests and responses:
RestResource(defaultRequestHeaders)
RestResource(defaultResponseHeaders)
Default headers can also be specified programmatically by overriding the following methods:
The RestContext.REST_logger
property allows you to configure
logging for your resource.
The interface is shown below:
RestLogger
log(Level,String,Object[])
log(Level,Throwable,String,Object[])
logObjects(Level,String,Object[])
onError(HttpServletRequest,HttpServletResponse,RestException)
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.
logger.logObjects(
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:
If your resource extends from RestServlet
, you can also
use and override the following methods:
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:
Unauthorized | A guard prevented the method from being executed |
|
Not Found | No matching path patterns were found on any method | |
Method Not Implemented | A path pattern matched, but no Java methods were found for the HTTP method | |
Not Acceptable |
A path pattern matched, but no Java methods were found with a matching serializer for the
|
|
Precondition Failed |
A path pattern matched, but no Java methods were found that were not rejected by
matchers
|
|
Unsupported Media Type |
A path pattern matched, but no Java methods were found with a matching parser for the
|
|
Internal Server Error | The Java method threw an exception other than RestException |
Through the use of the built-in
For example, the URL
To support overloaded methods, the @RestResource(allowedMethodParams)
setting must be enabled on your servlet.
The following URL parameters have special meaning and can be passed in through the URL of the request:
&plainText=true |
Response will always be 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 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. |
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
Since REST servlets are basically just
The following code shows how to register your REST servlets in an OSGi
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.
The API consists of the following classes:
org.apache.juneau.rest.mock
MockRest
MockServletRequest
HttpServletRequest
with additional convenience methods for building requests.
MockServletResponse
HttpServletRequest
with additional convenience methods for testing responses.
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.
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:
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.
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:
Next, define the Spring configuration to return our resolver:
Finally, define your Root
resource with a constructor that takes in our rest resource resolver and
sets it on the config object during initialization.
After that, just define constructors on your child resources to take in Spring beans:
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.
GenericServlet.init(ServletConfig)
or GenericServlet.init()
for initialization just like any other servlet.
juneau-rest-server-jaxrs-8.0.0.jar
org.apache.juneau.rest.server_8.0.0.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.
The Juneau framework contains the
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:
@RestMethod
and JuneauProvider
annotations.
What you can't do with the Juneau JAX-RS provider classes:
HtmlDocSerializer
class.
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
juneau-rest-server-springboot-8.0.0.jar
org.apache.juneau.rest.server.springboot_8.0.0.jar
The juneau-rest-server-springboot
library provides classes to make it easy to integrate
Juneau REST resources with Spring and Spring Boot.
The Juneau integration component for Spring Boot consists of the following classes:
A typical Spring Boot application can use the JuneauRestInitializer
to find
and register Juneau REST servlets via the JuneauRestRoot
annotation.
The initializer will search for Spring beans annotated with the
Another option is to use the
The root servlets are given an instance of SpringRestResourceResolver
which allows
for child resources to be defined as injectable Spring beans.
The Overview > juneau-examples-rest-springboot section describes how the Examples REST application is deployed using Spring Boot and quickly deployable as an online application using Heroku.
juneau-rest-client-8.0.0.jar
org.apache.juneau.rest.client_8.0.0.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.
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.
Serializer
classes.
Parser
classes.
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
RestClient
class exposes all the builder methods on the Apache
HttpClient HttpClientBuilder
class.
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.
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 }
The @RemoteResource
annotation is used on your interface class
to identify it as a REST proxy interface.
The
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.
PetStore p = client.getRemoteResource(PetStore.
When a relative path is specified, it's relative to the root-url defined on the RestClient
used to instantiate the interface.
RestClient client = RestClient.
When no path is specified, the root-url defined on the RestClient
is used.
RestClient client = RestClient.
The @RemoteMethod
annotation is applied to methods
of
The HTTP method and path are mapped to a Java method using the method
and path
annotations.
The Java method name can be anything.
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
:
In such cases, the
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)
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 |
The return type of the Java methods of can be any of the following:
RestClient
based on the Content-Type
of the response.
@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
:
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.
The @Body
annotation can be applied to arguments of
The argument can be any of the following types:
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 InputStream
- Raw contents of InputStream
will be serialized to remote resource.
Content-Type
is set to NameValuePairs
- Converted to a URL-encoded FORM post.
Content-Type
is set to HttpEntity
- Bypass Juneau serialization and pass HttpEntity directly to HttpClient.
OpenAPI schema based serialization can be used by using the OpenApiSerializer
class.
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.
The @FormData
annotation can be applied to arguments of
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.
Single-part arguments (i.e. those with name !=
HttpPartSerializer
registered with the
RestClient
(OpenApiSerializer
by default) or associated via the @FormData(serializer)
annotation.
Multi-part arguments (i.e. those with name ==
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.
HttpPartSerializer
(OpenApiSerializer
by default).
HttpPartSerializer
(OpenApiSerializer
by default).
CharSequence
- Used directly as am See the link below for information about supported data types in OpenAPI serialization.
The @Query
annotation can be applied to arguments of
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.
Single-part arguments (i.e. those with name !=
HttpPartSerializer
registered with the
RestClient
(OpenApiSerializer
by default) or associated via the @Query(serializer)
annotation.
Multi-part arguments (i.e. those with name ==
Reader
- Raw contents of Reader
will be serialized directly a query string.
NameValuePairs
- Serialized as individual query parameters.
Map
- Converted to key-value pairs.
HttpPartSerializer
(OpenApiSerializer
by default).
HttpPartSerializer
(OpenApiSerializer
by default).
CharSequence
- Serialized directly a query string.
See the link below for information about supported data types in OpenAPI serialization.
The @Header
annotation can be applied to arguments of
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.
Single-part arguments (i.e. those with name !=
HttpPartSerializer
registered with the
RestClient
(OpenApiSerializer
by default) or associated via the @Header(serializer)
annotation.
Multi-part arguments (i.e. those with name ==
NameValuePairs
- Serialized as individual headers.
Map
- Converted to key-value pairs.
HttpPartSerializer
(OpenApiSerializer
by default).
HttpPartSerializer
(OpenApiSerializer
by default).
See the link below for information about supported data types in OpenAPI serialization.
The @Path
annotation can be applied to arguments of
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.
Single-part arguments (i.e. those with name !=
HttpPartSerializer
registered with the
RestClient
(OpenApiSerializer
by default) or associated via the @Path(serializer)
annotation.
Multi-part arguments (i.e. those with name ==
NameValuePairs
- Serialized as individual query parameters.
Map
- Converted to key-value pairs.
HttpPartSerializer
(OpenApiSerializer
by default).
HttpPartSerializer
(OpenApiSerializer
by default).
See the link below for information about supported data types in OpenAPI serialization.
The @Request
annotation can be applied to a type of a
Request
partSerializer
- Override the part serializer.
PetStore store = restClient.getRemoteResource(PetStore.
The
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:
The @Response
annotation can be applied to types returned by
Response
partParser
- Override the part parser.
The
PetStore store = restClient.getRemoteResource(PetStore.
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.
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
The general approach is to define your @RemoteResource
-annotated interface first.
The following example is pulled from the PetStore app:
Next you define the implementation of your interface as a normal Juneau REST resource:
Then use the interface as a remote resource like so:
In the example above, we chose to add the
Note how we didn't need to use the
The simplest way to enable SSL support in the client is to use the
RestClientBuilder.enableLaxSSL()
method.
A more typical scenario using default cert and hostname verification is shown here:
RestClient rc = RestClient.create().enableSSL().sslProtocols(
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)
.
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.
The RestClientBuilder.basicAuth(String,int,String,String)
method
can be used to quickly enable BASIC authentication support.
This is functionally equivalent to the following:
RestClientBuilder builder = RestClient.
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.
The following example shows how the JazzRestClient
class provides OIDC authentication
support.
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.
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:
The RestCall.failurePattern(String)
method does the opposite.
It throws an exception if a failure message is detected.
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
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.
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.
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
=== 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 ========================================================================
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.
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.
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.
The MockRest
class is used for performing serverless unit testing of REST interfaces.
The RestClientBuilder.mockHttpConnection(MockHttpConnection)
method is used to associate a MockRest
with
a RestClient
to allow for serverless testing of clients.
Mocked connections can also be used for serverless testing of remote resources and interfaces.
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.
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.
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.
juneau-microservice-core-8.0.0.jar
org.apache.juneau.microservice.core_8.0.0.jar
Juneau Microservice is an API for creating stand-alone executable jars with automatic support for Juneau configurations and console commands.
Features include:
The Microservice API consists of a base class for defining executable microservices.
Features include:
The Microservice API consists of the following packages and classes:
org.apache.juneau.microservice
Microservice
- The base microservice class.
MicroserviceBuilder
- Builder for the microservice class.
MicroserviceListener
- Interface for hooking into lifecyle events of the microservice.
BasicMicroserviceListener
- Adapter for MicroserviceListener class.
org.apache.juneau.microservice.console
ConsoleCommand
- Abstract class for defining console commands.
By itself the Microservice API doesn't provided much functionality, but it does provide the basis for the Jetty Microservice described later.
The most-basic creation of a microservice from an entry-point method is shown below:
The lifecycle methods of the Microservice
class consists of the following:
A typical implementation of an app with lifecycle methods might look like the following:
If your application consists of a single microservice, you can use the Microservice.getInstance()
method
from anywhere in your code:
The Microservice.startConsole()
and Microservice.stopConsole()
control
the lifecycle of the console commands.
Typically you'll want to control these separately from the app so that you can easily restart your application
from the console without affecting the console itself.
The lifecycle methods on the Microservice
class are purposely left non-final so that
subclasses can override them to provide customized behavior.
Command-line arguments can be associated with a microservice using the MicroserviceBuilder.args(String...)
method.
When specified, the arguments can be retrieved using the Microservice.getArgs()
method which provides
an API for easily accessing command-line arguments using common notation:
Args a = Microservice.
Specifying the command-line arguments also makes them available through $A
SVL variables.
These can be used in the configuration file and throughout various Juneau annotations.
The MicroserviceBuilder.manifest(Object)
method can be used to specify the contents or location of of the main
manifest file of the executable jar.
If you do not specify the location/contents of the manifest file, the microservice will attempt to resolve it through the following methods:
If you do manually specify the manifest file, you can pass in any of the following types:
ManifestFile
- A pre-parsed manifest file.
Manifest
- A pre-parsed manifest file.
Reader
- Containing the raw contents of the manifest.
InputStream
- Containing the raw contents of the manifest.
File
- File containing the raw contents of the manifest.
String
- Path to file containing the raw contents of the manifest.
Class
- Finds and loads the manifest file of the jar file that the specified class is contained within.
The manifest file can be retrieved using the the Microservice.getManifest()
method which
provides an API for accessing manifest file entries.
This method returns an instance of ManifestFile
which extends from ObjectMap
allowing
you to retrieve entries as any data types supported by that class.
ManifestFile mf = Microservice.
The manifest is also used for the $MF
SVL variable.
The following methods can be used to define the configuration for your microservice using the powerful Config API:
If you do not specify any of this information, we attempt to resolve it through the following methods:
Main-Config
entry in the manifest file.
If no configuration file is found, and empty in-memory configuration is used.
The configName(String)
method allows you to explicitly specify the name
of the external configuration file location for your microservice.
Microservice
.
By default, we try to find the file on the file system and then the classpath. If located on the file system, then the configuration is writeable and the microservice can automatically listen for and react to changes in the configuration file on the file system. If located on the classpath, then the configuration can still react to modifications made to it through the Config API, but the changes cannot be persisted since the location prevents the file from being modified.
The configStore(ConfigStore)
method can be used to explicitly
specify a configuration store.
This can include your own custom configuration store, such as one that's implemented in a relational database.
Microservice
.
The config(Config)
method can be used to explicitly specify a Config
file as the microservice configuration. When this method is used, the above two methods are bypassed entirely.
Config config =
Once the configuration is resolved, it is made as the system default configuration available through the Config.getSystemDefault()
.
This in turn allows it to be used by REST resources that reference the system default configuration via the BasicRestConfig
interface.
The Microservice.getConfig()
method can be used to get access to the configuration.
Config c = Microservice.
Changes to the configuration file can trigger notifications that can be used to restart your microservice or make various other
on-the-fly changes.
This can be accomplished by either overriding the Microservice.onConfigChange(ConfigEvents)
or implementing
a listener and using the MicroserviceListener.onConfigChange(Microservice,ConfigEvents)
methods.
These will be described in detail later.
As a convenience, the SystemProperties
section of your configuration file can be used to define system
properties to set during initialization of your microservice:
The Microservice API incorporates the Simple Variable Resolver API.
The variable resolver can be augmented through the following methods:
A typical usage pattern is shown below:
The variable resolver becomes much more powerful when used in REST resource annotations which will be described latter in Overview > juneau-microservice-jetty
By default, support for the following variables are provided:
$S{key[,default]}
- SystemPropertiesVar
$E{key[,default]}
- EnvVariablesVar
$A{key[,default]}
- ArgsVar
$C{key[,default]}
- ConfigVar
$MF{key[,default]}
- ManifestFileVar
$IF{arg,then[,else]}
- IfVar
$SW{arg,pattern1:then1[,pattern2:then2...]}
- SwitchVar
$CO{arg[,arg2...]}
- CoalesceVar
$PM{arg,pattern}
- PatternMatchVar
$UC{arg}
- UpperCaseVar
$LC{arg}
- LowerCaseVar
$NE{arg}
- NotEmptyVar
The Microservice API provides support for simple console commands.
When started, the console renders the following output:
Running class 'Microservice' using config file 'my-microservice.cfg'. List of available commands: exit -- Shut down service restart -- Restarts service help -- Commands help >
The builder methods for controlling the console are as follows:
By default, the supported commands are pulled from the configuration file:
New commands can be added by adding them to the configuration file, or programmatically using the consoleCommands(ConsoleCommand...)
builder method.
The API for defining console commands is shown below:
By default, the console input and output are taken from System.in
and System.out
.
These can be overridden using the console(Scanner,PrintWriter)
method.
The Microservice API provides build-in but configurable and overridable support for logging.
The method for configuring logging is as follows:
If not specified, the logging configuration is pulled in from the configuration file:
The logging configuration can also be defined programmatically through the following API:
If you wish to bypass the default logging configuration entirely, you can pass in your own logger via
the MicroserviceBuilder.logger(Logger)
method.
In addition to configuring the built-in Java logging framework, the following convenience methods are also
provided on the Microservice
class for logging.
As mentioned previously, the lifecycle methods for the Microservice
class are explicitly
defined as non-final so that they can be overridden by subclasses.
In addition to this support, an interface for defining event listeners for your microservice:
This listener API can be used for listening for and reacting to configuration changes on the file system.
Note that the Microservice.onConfigChange(ConfigEvents)
method can also be overridden
to react to configuration changes as well:
juneau-microservice-jetty-8.0.0.jar
org.apache.juneau.microservice.jetty_8.0.0.jar
Juneau Microservice Jetty 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.
The Jetty Microservice API consists of a combination of the Juneau Core, Server, and Client APIs and an embedded Eclipse Jetty Servlet Container.
The API builds upon the Core Microservice classes to produce easy-to-create and easy-to-use microservices in a standard Java 1.8+ environment.
The juneau-microservice-jetty
library consists of the following classes:
org.apache.juneau.microservice.jetty
JettyMicroservice
- The Jetty microservice class.
JettyMicroserviceBuilder
- Builder for the microservice class.
JettyMicroserviceListener
- Interface for hooking into lifecyle events of the microservice.
BasicJettyMicroserviceListener
- Adapter for JettyMicroserviceListener class.
JettyServerFactory
- Interface for defining custom Jetty servers.
BasicJettyServerFactory
- Adapter for JettyServerFactory class.
The most-basic creation of a Jetty microservice from an entry-point method is shown below:
To review, the Microservice
class contains the following lifecycle methods:
The JettyMicroservice
class which extends from Microservice
provides the following additional lifecycle methods:
The additional lifecycle methods are typically not called directly, but are exposed to allow subclasses to provide customized behavior for these events. For this reason, these methods are left as non-final so that they can be overridden.
A typical implementation of an app with lifecycle methods might look like the following:
Similar to Microservice.getInstance()
, the JettyMicroservice.getInstance()
also allows easy access to the microservice:
This section describes how to define a top-level REST resource page and deploy it in our microservice. The example is a router page that serves as a jumping off page to child resources.
When deployed, it looks like this in a browser:
http://localhost:10000
BasicRestServlet
or other resource groups.
If you click the
http://localhost:10000/helloWorld
...which is generated by this class...
The most-common case for deploying the top-level resource is to use the JettyMicroserviceBuilder.servlet(Class)
method:
However, there are multiple ways of deploying top-level resources:
JettyMicroserviceBuilder.servlet(Class)
- Using the builder. Several methods provided.
JettyMicroservice.addServlet(Servlet,String)
- After the Jetty container has been started.
jetty.xml
file.
The following predefined resource classes are also provided for easy inclusion into your microservice:
ConfigResource
- View and modify the external INI config file.
DirectoryResource
- View and modify file system directories.
LogsResource
- View and control generated log files.
SampleRootResource
- A sample root resource class to get started from.
ShutdownResource
- Shutdown and/or restart the JVM.
In Overview > juneau-microservice-core > Config, we described how to associate a configuration file with your microservice. In this section we describe how that configuration can be used to customize the behavior or your REST resource classes.
The most common usage for the configuration file is to reference values using the $C
variable in annotations.
For example, the BasicRestConfig
interface that defines the annotations that control the look-and-feel of
classes that extend from BasicRestServlet
use several $C
variables to externalize values:
These values in turn are pulled from the external configuration file shown below.
Note that the configuration file can also contain $C
variables.
Configuration files can also be accessed programmatically. 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.
Additional user-defined variables at the servlet level can be defined 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.
Additional user-defined variables can be defined at this level by overriding the
RestContextBuilder.vars(Class...)
method.
That
This particular example is needlessly complex, but it gives an idea of how variables can be used recursively to produce sophisticated results
The Jetty microservice comes with a bare-bones jetty.xml
file which can be modified to suite any needs.
The jetty.xml
can be located in either the
JettyMicroserviceBuilder.jettyXml(Object,boolean)
method to specify the location or contents
of the file.
Jetty-Config
value in the MANIFEST.MF
file.
SVL variables in the jetty.xml
file are automatically resolved by the microservice.
This allows you to reference values in your configuration file from the jetty.xml
file.
The HTTP port used is controlled via the following:
JettyMicroserviceBuilder.ports(int...)
method.
JettyMicroservice
.
The first available port is then made available through the system property jetty.xml
file.
The JettyMicroserviceBuilder.jettyServerFactory(JettyServerFactory)
method is also provided
to use your own customized Jetty server.
The Microservice project contains a files/htdocs
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:
The BasicRestConfig
interface (which defines the default settings for BasicRestServlet
pulls in this information using $C
and $U
variables:
Note that the files/htdocs
directory is mapped to staticFiles
setting. This allows those files to be served up through the servlet through the URL
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:
This example shows how the JettyMicroservice
class
can be extended to implement lifecycle listener methods or override existing methods.
We'll create a new class
Optionally, you can extend the JettyMicroserviceBuilder
class as well:
my-jetty-microservice-8.0.0.zip
The
It includes a combination of the Juneau Core, Server, and Client APIs and all libraries needed to execute in a Java 1.8+ environment.
Follow these instructions to create a new template project in Eclipse.
my-jetty-microservice-8.0.0.zip
file from the downloads page
(located in the binaries) and import it into your workspace as an existing project:
The important elements in this project are:
At this point, you're ready to start the microservice from your workspace.
The
Go to Run -> Run Configurations -> Java Application -> my-jetty-microservice and click Run. In your console view, you should see the following output:
Running class 'JettyMicroservice' using config file 'my-jetty-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 can enter the command exit
to shut it down.
The
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-jetty-microservice-1.0.jar
my-jetty-microservice.cfg
To start from a command line, run the following command from inside your target
directory:
java -jar my-jetty-microservice-1.0.jar
You should see the following console output:
Running class 'JettyMicroservice' using config file 'my-jetty-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.
my-springboot-microservice-8.0.0.zip
The
It includes a combination of the Juneau Core, Server, and Client APIs and all libraries needed to execute in a Java 1.8+ environment.
One significant difference is that we are not using the Juneau Microservice
API for our
application but instead using the existing Spring Boot API.
Follow these instructions to create a new template project in Eclipse.
my-springboot-microservice-8.0.0.zip
file from the downloads page
(located in the binaries) and import it into your workspace as an existing project:
The important elements in this project are:
@JuneauRestRoot
At this point, you're ready to start the microservice from your workspace.
The
Go to Run -> Run Configurations -> Java Application -> my-springboot-microservice and click Run. In your console view, you should see the following output:
. ____ _ __ _ _ /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ \\/ ___)| |_)| | | | | || (_| | ) ) ) ) ' |____| .__|_| |_|_| |_\__, | / / / / =========|_|==============|___/=/_/_/_/ :: Spring Boot :: (v2.0.1.RELEASE) ... INFO: Tomcat started on port(s): 8080 (http) with context path '' Dec 21, 2012 12:30:00 AM org.springframework.boot.StartupInfoLogger logStarted INFO: Started App in 1.999 seconds (JVM running for 2.999)
Now open your browser and point to
http://localhost:5000
The
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-springboot-microservice-1.0.jar
To start from a command line, run the following command from inside your target
directory:
java -jar my-springboot-microservice-1.0.jar
You should see the following console output:
. ____ _ __ _ _ /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ \\/ ___)| |_)| | | | | || (_| | ) ) ) ) ' |____| .__|_| |_|_| |_\__, | / / / / =========|_|==============|___/=/_/_/_/ :: Spring Boot :: (v2.0.1.RELEASE) ... INFO: Tomcat started on port(s): 8080 (http) with context path '' Dec 21, 2012 12:30:00 AM org.springframework.boot.StartupInfoLogger logStarted INFO: Started App in 1.999 seconds (JVM running for 2.999)
juneau-examples-core-8.0.0.zip
The juneau-examples-core
project contains various code examples for using the core APIs.
Follow these instructions to import the Juneau project into Eclipse.
juneau-examples-core-8.0.0.zip
file from the downloads page
(located in the binaries) and import it into your workspace as an existing project:
The following shows the core examples provided:
org.apache.juneau.examples.core.json
JsonSimpleExample
- JsonSerializer and JsonParser usage on serialize and deserialize simple Pojo bean.
JsonComplexExample
- JsonSerializer and JsonParser usage on serialize and deserialize complex Pojo bean.
JsonConfigurationExample
- Json Serializers configured using properties defined in JsonSerializer class.
org.apache.juneau.examples.core.xml
XmlSimpleExample
- XmlSerializer and XmlParser usage on serialize and deserialize simple Pojo bean.
XmlComplexExample
- XmlSerializer and XmlParser usage on serialize and deserialize complex Pojo bean.
XmlConfigurationExample
- XmlSerializers configured using properties defined in XmlSerializer class.
org.apache.juneau.examples.core.dto
DtoExample
- Usage of core dto module.
org.apache.juneau.examples.core.rdf
RdfExample
- RdfXmlSerializer usage on serialize simple Pojo bean.
RdfComplexExample
- RdfXmlSerializer usage on serialize complex Pojo bean.
org.apache.juneau.examples.core.html
HtmlSimpleExample
- HtmlSerializer usage on serialize and deserialize simple Pojo bean.
HtmlComplexExample
- HtmlSerializer usage on serialize and deserialize complex Pojo bean.
org.apache.juneau.examples.core.uon
UONExample
- UonSerializer usage on serialize and deserialize simple Pojo bean.
UONComplexExample
- UonSerializer usage on serialize and deserialize complex Pojo bean.
org.apache.juneau.examples.core.svl
SvlExample
- Usage of Svl module in juneau.
juneau-examples-rest-8.0.0.jar
org.apache.juneau.examples.rest_8.0.0.jar
The juneau-examples-rest
project includes various examples of REST resources written
using Juneau.
Note: These examples can be deployed as buildable Eclipse projects using Jetty or Spring Boot using instructions in the following sections:
The
The class hierarchy for this class is:
RestServlet
- Contains all the REST servlet logic.
BasicRestServlet
- Defines default serializers and parsers, and OPTIONs page logic.
BasicRestServletGroup
- Specialized subclass for grouping other resources.
BasicRestServletJenaGroup
- Group resource with added RDF support.
RootResources
Pointing a browser to the resource shows the following:
http://localhost:10000
The
The
The
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.
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
When a request for the child URL (
The
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 BasicRestServlet
class.
The only difference between implementing
All other examples in this project extend from
Pointing a browser to the resource shows the following:
http://localhost:10000/helloWorld
Using the special
http://localhost:10000/helloWorld?Accept=text/json&plainText=true
The PetStore
application is an functional application meant to demonstrate the following:
When you click the
http://localhost:10000/petstore
The contents of this page is primarily defined via annotations defined on the
The inner contents of the page are generated from this method which is used to define a jumping-off page for the application:
Note how we used the
The ResourceDescriptions
class used above is a convenience class for creating
hyperlinks to child resources.
The application itself is defined in 3 packages:
org.apache.juneau.rest.examples.rest.petstore
org.apache.juneau.rest.examples.rest.petstore.dto
org.apache.juneau.rest.examples.rest.petstore.rest
We also define some static files in the org.apache.juneau.rest.examples.rest.petstore
package:
The
The DTOs are simply beans that combine both JPA and Juneau bean annotations:
The beans are found by JPA by adding them to the JPA persistence file.
The Petstore service is instantiated in our REST interface using a hook. Note that a real-world scenario would likely use some other means such as injection.
The Petstore database is empty by default.
The
http://localhost:10000/petstore/init
You can try loading the Petstore database using direct JPA or via REST calls through a client-side proxy.
The initialize page is rendered using the following methods in our
The direct initialization uses direct JPA to store beans in the database.
The following code in
The REST initialization uses a REST proxy interface to delete and store values in the database:
The
Note that this is the same interface used to define our server-side REST implementation! The annotations defined on the method parameters used for client-side proxies are also inherited by and used for our server-side implementation class.
The advantage to using a common interface for both your server-side and client-side APIs is that you have less of a chance of a mismatch between the server and client side definitions.
Now that we've initialized the contents of our database, we can start exploring the REST interface.
We can start by click the
http://localhost:10000/petstore/pet
Clicking on one of the ID links takes you to a details page:
http://localhost:10000/petstore/pet/1
You'll notice the details page shows bpx=
annotation on the
The hyperlinks and special rendering for HtmlRender
objects.
The
http://localhost:10000/petstore/pet/1
For example, selecting
http://localhost:10000/petstore/pet?plainText=true&Accept=application%2Fjson%2Bsimple
Note that we're using the convenience feature for specifying an Accept
header via a query parameter.
The
http://localhost:10000/petstore/pet/1
For example, selecting
http://localhost:10000/petstore/pet?stylesheet=htdocs%2Fthemes%2Flight.css
Both the
The implementation of a menu item contains methods for retrieving the label and HTML5 content of the menu item.
The Queryable
converter.
http://localhost:10000/petstore/pet
The converter will take the POJOs to be serialized and filter them based on the provided query/view/sort/paging attributes:
http://localhost:10000/petstore/pet?s=name%3DHoppy*&v=species%2Cname&o=name&p=0&l=20
The
http://localhost:10000/petstore/pet
Both the
The
http://localhost:10000/petstore/pet?method=OPTIONS
Since we've defined tags on our annotations, the pet-related operations are all grouped under the
Information for all HTTP parts is automatically generated:
The schema models for POJO models is available in the
Auto-generated examples are available for all supported languages:
For example,
Examples can be derived in a number of ways. In our case, we've defined a static method on our
Similar functionality exists for request bodies as well:
At the bottom of the page is a listing of the POJO models in the app:
The
http://localhost:10000/petstore/photos
The
The contents of the home page simply renders our collection of photo beans:
Clicking on one of the hyperlinks renders the stored image for us:
http://localhost:10000/petstore/photos/cat
The method for retrieving images simply returns a
The OutputStreamSerializer
:
Likewise, the body of requests can also be instances of
The InputStreamParser
:
A custom menu item is provided for uploading new images:
http://localhost:10000/petstore/photos
The menu item is defined as a
The menu item then submits multi-part form posts to the following method:
The
http://localhost:10000/petstore/sql
For example, viewing all of the
http://localhost:10000/petstore/sql?sql=select+*+from+PetstorePet
The
The connection information is pulled from the
The query entry page is rendered using HTML5 beans:
The form then submits its results to the following method using a form input bean:
Note that we could have also used
The
The
Pointing a browser to the resource shows the following:
http://localhost:10000/atom
True ATOM feeds require using an
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
The
JSON Schema DTO
API.
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
http://localhost:10000/jsonSchema?Accept=text/json&plainText=true
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.
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
juneau-examples-rest-jetty-8.0.0.zip
The juneau-examples-rest-jetty
project includes everything you need create a Samples REST
microservice in an Eclipse workspace and build it as an executable jar.
Follow these instructions to import the REST examples project using Jetty into Eclipse.
juneau-examples-rest-jetty-8.0.0.zip
file from the downloads page
(located in the binaries) and import it into your workspace as an existing project:
The important elements in this project are:
At this point, you're ready to start the microservice from your workspace.
The
Go to Run -> Run Configurations -> Java Application -> juneau-examples-rest-jetty and click Run. In your console view, you should see the following output:
Running class 'JettyMicroservice' using config file 'juneau-examples-rest-jetty.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 can enter the command exit
to shut it down.
The
The easiest way to build the microservice is to run the following from the project root.
mvn clean install
Your target
directory should now contain the following files:
juneau-examples-rest-jetty-1.0.jar
juneau-examples-rest-jetty.cfg
To start from a command line, run the following command from inside your target
directory:
java -jar juneau-examples-rest-jetty-1.0.jar
You should see the following console output:
Running class 'JettyMicroservice' using config file 'juneau-examples-rest-jetty.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.
juneau-examples-rest-springboot-8.0.0.zip
The juneau-examples-rest-springboot
library contains the same examples as juneau-examples-rest
but also includes the following:
spring-boot-starter-parent
that allows you to build a fully-shaded executable jar.
Follow these instructions to import the REST examples project using Spring Boot into Eclipse.
juneau-examples-rest-springboot-8.0.0.zip
file from the downloads page
(located in the binaries) and import it into your workspace as an existing project:
The important elements in this project are:
@JuneauRestRoot
At this point, you're ready to start the microservice from your workspace.
The
Go to Run -> Run Configurations -> Java Application -> juneau-examples-rest-springboot and click Run. In your console view, you should see the following output:
. ____ _ __ _ _ /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ \\/ ___)| |_)| | | | | || (_| | ) ) ) ) ' |____| .__|_| |_|_| |_\__, | / / / / =========|_|==============|___/=/_/_/_/ :: Spring Boot :: (v2.0.1.RELEASE) ... INFO: Tomcat started on port(s): 8080 (http) with context path '' Dec 21, 2012 12:30:00 AM org.springframework.boot.StartupInfoLogger logStarted INFO: Started App in 1.999 seconds (JVM running for 2.999)
Now open your browser and point to
http://localhost:5000
The
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:
juneau-examples-rest-springboot-1.0.jar
To start from a command line, run the following command from inside your target
directory:
java -jar juneau-examples-rest-springboot-1.0.jar
You should see the following console output:
. ____ _ __ _ _ /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ \\/ ___)| |_)| | | | | || (_| | ) ) ) ) ' |____| .__|_| |_|_| |_\__, | / / / / =========|_|==============|___/=/_/_/_/ :: Spring Boot :: (v2.0.1.RELEASE) ... INFO: Tomcat started on port(s): 8080 (http) with context path '' Dec 21, 2012 12:30:00 AM org.springframework.boot.StartupInfoLogger logStarted INFO: Started App in 1.999 seconds (JVM running for 2.999)
Heroku is a platform-as-a-service that allows applications to be quickly hosted
in the cloud.
The
{
web: java -jar target/juneau-examples-rest-springboot-8.0.0.jar
You'll need to sign up for an account on Heroku. Afterwards, you can go to the apps page to create a new application:
https://dashboard.heroku.com/apps
Click the
https://dashboard.heroku.com/new-app
After clicking the
https://dashboard.heroku.com/apps/juneau-examples-rest/deploy/heroku-git
For this example, we'll use the
https://dashboard.heroku.com/apps/juneau-examples-rest/deploy/heroku-git
Next, run the following commands to cd into our Eclipse project and initialize it as a local git repo:
$ cd juneau-examples-rest-springboot/ $ git init
$ cd juneau-examples-rest-springboot/ $ git init Initialized empty Git repository in /.../juneau-examples-rest-springboot/.git/
Next, run the following command to link our project to the Heroku app:
$ heroku git:remote -a juneau-examples-rest
$ heroku git:remote -a juneau-examples-rest set git remote heroku to https://git.heroku.com/juneau-examples-rest.git
Next, run the following commands to add our files to the git repo and push to the Heroku master branch:
$ git add . $ git commit -am "Initial deploy" $ git push heroku master
$ git add . master (root-commit) 7c94cb9] Initial deploy 123 files changed, 11986 insertions(+) Counting objects: 127, done. $ git commit -am "Initial deploy" $ git push heroku master Delta compression using up to 8 threads. Compressing objects: 100% (113/113), done. Writing objects: 100% (127/127), 363.91 KiB | 21.41 MiB/s, done. ... remote: -----> Compressing... remote: Done: 85.9M remote: -----> Launching... remote: Released v3 remote: https://juneau-examples-rest.herokuapp.com/ deployed to Heroku remote: remote: Verifying deploy... done. To https://git.heroku.com/juneau-examples-rest.git * [new branch] master -> master
If no errors were shown, then our application should now be live.
You can click on the
If everything worked, your browser should now be loaded with our example REST app:
https://juneau-examples-rest.herokuapp.com
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:
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
Fortunately, Juneau does not support an open-ended JsonParser.
).
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:
Juneau does support something similar to a
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:
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.
When accessing security vulnerabilities of any library, dependent libraries must also be taken into account:
7.0.1
, no known security vulnerabilities exist that affect Juneau at this time.
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
An example of a potential security hole is shown below that could potentially expose any file on a file system through a REST request:
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 $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 $R
variable, so the $F
variable in the result will never get processed and instead be treated as plain text.
$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.
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.
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.
BeanContext
.Transform
class, which is associated with the BeanContext
class (and thus the Serializer and Parser classes too) through the BeanContext.addTransforms(Class[])
method.Transform
:
BeanFilter
- Filter POJO beans.PojoSwap
- Filter POJOs that aren't beans.Cast
and BeanFilter
APIs which were considerably more complicated and puts them under a common API.
_class
attributes in parsable output.BeanMap
API.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.
RestServlets
.PojoIntrospector
class.
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.
OPTIONS
pages for resources.
RestServlet
.
Enum
.
MyBeanList extends LinkedList<MyBean>
).
HtmlParser
and UrlEncodingParser
classes.
Juno 5.0.0.1 is a moderate update.
Juno 5.0.0.2 is a minor update.
org.apache.juneau.json
).
Enum
keys, and parsing Enum
strings.ObjectList.toXArray()
methods with a new elements(Class<T> type)
method that's more efficient and avoids creating an unnecessary array.
@BeanConstructor
annotation allows you to specify bean property values to be passed in through a constructor.
Juno 5.0.0.3 is a minor update.
@BeanConstructor
annotation has been added.
SerializerGroups
and ParserGroups
now share BeanContexts
to reduce memory consumption of class type metadata.
Juno 5.0.0.4 is a minor update.
@RestMethod
annoation on RestServlet
methods.RestServlet
for more information.
BeanContext.convertToType(Object,Class)
to be able to convert Strings
to classes with
fromString(String)
/valueOf(String)
static methods or T(String)
constructors.
Juno 5.0.0.5 is a major update.
@RestChild
annotation for identifying child resources.traversable
and filterable
attributes added to @RestMethod
annotation.PojoResource
and FilteredRestResource
classes.
resourceUri
attributed added to HtmlSerializer
.XmlSerializer
.RdfXmlSerializer
.Juno 5.0.0.6 is a minor update that fixes a small bug in 5.0.0.5.
Juno 5.0.0.7 is a major update.
ParserListener
class.XmlParser
:
@Xml.format
annotation.@Xml.namespaces
annotation.@Xml.nsUri
annotation.@Xml.valAttr
annotation.BeanContext
SerializerContext
ParserContext
BeanContext
:
@BeanProperty(hidden)
so that they don't get serialized.
ClassType
ClassMeta
API.@Bean.filter
and @BeanProperty.filter
annotations.BeanContext.addTransforms(Class[])
.
PropertyNamer
API / @Bean.propertyNamer
annotation.@BeanProperty.beanUri
and @BeanProperty.id
annotations.rdf:resource
attributes.
@BeanProperty(properties)
annotation.
Used for limiting properties on child elements.
URL
and URI
objects.
PojoQuery
support.
RestResponse.setProperty(String,Object)
method.@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.@RestMethod(filters)
- Associate post-formatting filters on a method level.@RestMethod(guards)
- Associate method-level guards.@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.RestResponse.setOutput(Object)
.
Juno 5.0.0.8 is a minor update.
INI file
support.
Juno 5.0.0.9 is a moderate update.
INI config file support
:
@Bean
annotation to override bean identification settings.ObjectMap.cast(Class)
method to convert ObjectMaps
directly to beans.OPTIONS
pages.@RestResource.defaultRequestHeaders
and @RestResource.defaultResponseHeaders
annotations.@RestMethod(serializers)
and @RestMethod(parsers)
annotations.@RestMethod(properties)
annotation.@RestMethod(defaultRequestHeaders)
annotation.@RestMethod(matchers)
annotation and RestMatcher
class.Readers
and InputStreams
can be specified on @Content
annotated parameters.@HasParam
annotation.Accept
headers to serializers.Juno 5.0.0.10 is a minor update.
ObjectMap.findKeyIgnoreCase(String)
method.
RestServletProperties
class that defines all the class-level properties that can be set on the servlet.@RestResource.properties
annotation, or new RestServlet.setProperty(String,Object)
method.RestServletProperties.REST_useStackTraceHashes
property to prevent the same stack trace from being logged multiple times.RestServletProperties.REST_renderResponseStackTraces
property for preventing stack traces in responses for security reasons.RestServlet.onError(HttpServletRequest,HttpServletResponse,RestException,boolean)
and RestServlet.onSuccess(RestRequest,RestResponse,long)
methods for plugging in your own logging and peformance monitoring.RestServlet.getInitParams()
method, since it's now redundant with RestServlet.getProperties()
.Juno 5.0.0.11 is a moderate update.
UrlEncodingRestSerializer
and UrlEncodingRestParser
classes.Accept
and Content-Type
BasicRestServlet
.
RestServlet.renderError(HttpServletRequest,HttpServletResponse,RestException)
method to allow customized handling of response errors.
Juno 5.0.0.12 is a minor update.
@BeanProperty
annotation.BeanProperty.method
annotation, since it's now unnecessary.
PlainTextRestSerializer
class for serializing 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.RestRequest.getInputStream()
and RestRequest.getReader()
.
?debug
parameter.Juno 5.0.0.13 is a minor update.
SerializerContext.SERIALIZER_uriContext
and SerializerContext.SERIALIZER_uriAuthority
serializer properties for specifying values for relative URIs.
@URI
annotation that allows you to specify classes and bean properties as URLs that aren't java.net.URI
or java.net.URL
.
HtmlSerializer.HTML_uriAnchorText
HTML serializer property for tailoring how anchor text is rendered.
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.
BeanProperty#id
annotation.
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.Accept-Charset
header in Chrome that prevented HTML output from rendering correctly in that browser.Accept-Charset
handling should now be fully W3C compliant.
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.
org.apache.juneau.serializer
package.
WriterSerializer
base class for defining character-based serializers.OutputStreamSerializer
base class for defining byte-based serializers.SerializerGroup
class with full support for RFC2616 Accept-Content
headers.org.apache.juneau.parser
package.
ReaderParser
base class for defining character-based parsers.InputStreamParser
base class for defining byte-based parsers.org.apache.juneau.transform
package.
BeanFilter
class for defining property filters on beans.PojoQuery
class for defining filters on objects (previously called ObjectFilter
).org.apache.juneau.encoders
package.
Encoders
for enabling compression in REST servlets and clients.GzipEncoder
class for enabling gzip compression.EncoderGroup
class for managing multiple encoders and finding them based on RFC2616 Accept-Encoding
header values.org.apache.juneau.plaintext
package.
PlainTextSerializer
and PlainTextParser
classes for serializing/parsing text/plain content.org.apache.juneau.jso
package.
JsoSerializer
class for serializing application/x-java-serialized-object
content.org.apache.juneau.soap
package.
SoapXmlSerializer
class for serializing text/xml+soap
content.BeanContext
class.
JsonMap
and JsonList
changed to ObjectMap
and ObjectList
to better reflect that they're not limited to just JSON support.
PojoSwap
to PojoQuery
to not confuse it with the new Filter API.
org.apache.juneau.rest.serializers
and org.apache.juneau.rest.parsers
packages.
RestClient
API.
Encoders
.RestCmdLine
(since it's essentially redundant with CURL).
Juno 5.0.0.15 is a moderate update.
@Produces
annotation in place of ISerializer.getMediaTypes()
for specifying what media types a serializer produces.Serializer
.
@Consumes
annotation in place of IParser.getMediaTypes()
for specifying what media types a parser consumes.Parser
.
Juno 5.0.0.16 is a minor update.
@Properties
REST method parameter annotation that can be used to get the runtime properties map through a parameter instead of through RestResponse
.
Juno 5.0.0.17 is a minor update.
IOutputStreamSerializer.serialize()
and IInputStreamParser.parse()
.
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.
JsoParser
class.
Juno 5.0.0.19 is a minor update.
RestServlet
:
RestServlet.onPreCall(RestRequest)
RestServlet.onPostCall(RestRequest,RestResponse)
SerializerContext.SERIALIZER_trimNullProperties
.Juno 5.0.0.20 is a major update.
RdfSerializer
for serializing POJOs to RDF/XML, RDF/XML-ABBREV, N-Triple, Turtle, and N3.RdfParser
for parsing RDF/XML, RDF/XML-ABBREV, N3, Turtle, and N-Triple back into POJOs.
XmlSerializerContext.XML_autoDetectNamespaces
default changed to XmlSerializerContext.XML_namespaces
annotation.@RestResource
annotation.@RestMethod
annotation:
RestMethod.filters()
annotation for defining POJO filters at the method level.
RestMethod.serializersInherit()
and RestMethod.parsersInherit()
annotations for controlling how serializers and parsers (and associated filters and properties) are inherited from the class.addSerializers
and addParsers
annotations.
RestServletJenaDefault
servlet that includes serialization/parsing support for all Jena-based serializers and parsers.
DefaultJenaProvider
JAX-RS provider that includes serialization/parsing support for all Jena-based serializers and parsers.
RestServletChild
class.RestServlet
:
RestServlet.createConfigFactory()
RestServlet.createSerializers()
RestServlet.createParsers()
getBeanContext()
/ getSerializers()
/ getParsers()
methods.
RestCall.setDateHeader(String,Object)
method for setting ISO8601 datetime headers.
Juno 5.0.0.21 is a minor update.
HtmlDocSerializerContext.HTMLDOC_navlinks
annotation for addint links to HTML page views.
HtmlDocSerializerContext
for clarity.
RestServlet.addDefaultProperties(ObjectMap,RestRequest)
method for programatically adding properties to the property map per request.
SerializerContext.SERIALIZER_uriAuthority
and SerializerContext.SERIALIZER_uriContext
properties were previously available.
RestServletProperties.REST_servletPath
RestServletProperties.REST_pathInfo
RestServletProperties.REST_method
@Attr
are now automatically URL-decoded.
Juno 5.0.0.22 is a minor update.
@Property .nls()
annotation for specifying localized property values.AddressBookResource
class for an example.
&Content
query parameter was not always parsed correctly.Juno 5.0.0.23 is a minor update.
Cognos
support.
@Xml
annotation was not being inherited by inner classes.
Juno 5.0.0.24 is a major update.
ATOM
.
AtomFeedResource
class added to sample war.
XmlFormat.CONTENT
enum value.XmlContentHandler
class and @Xml.contentHandler
annotation.@XmlSchema
and updated @XmlNs
annotations to better mimic JAXB.
@Xml .valAttr
annotation since it's now redundant with @Xml (format=CONTENT )
.
CalendarSwap
.
Serializer.serialize(Object,Object,SerializerContext)
method.
ObjectMap.getObjectList(String)
were not updatable.
JSON Support Overview
document.XML Support Overview
document.RDF Languages Support Overview
document.ATOM Support Overview
document.Juno 5.0.0.25 is a minor update.
ResultSetList
DTO for serializing SQL result sets to JSON/XML/HTML and so forth.
SqlQueryResource
class in the sample war for demonstrating the ResultSetList
DTO.
Servlet.init()
so that getProperties()
can be called during servlet initialization.
@Property .type
annotation with support for using system properties as resource properties.
Juno 5.0.0.26 is a minor update.
@RestResource(children)
defined on the resource class itself.@RestResource(path)
.
ChildResourceDescriptions
bean for automatically generating the contents of router resource pages.
@RestMethod .pattern()
to @RestMethod(path)
for naming consistency.
Juno 5.0.0.27 is a moderate update.
HtmlSerializer
.
BasicRestServlet
now includes PlainTextSerializer
and PlainTextParser
for plain-text support.
OPTIONS
pages through new method ResourceOptions.getChildren()
.
UrlEncodingSerializer
/UrlEncodingParser
to reduce the need for quoted string values.Juno 5.0.0.28 is a moderate update.
OutOfMemoryError
and performance issue caused by incorrect caching of class metadata.
WriterSerializer.serialize(Object,Writer)
convenience method for serializing directly to a writer.Juno 5.0.0.29 is a moderate update.
BeanFilter
class to mirror the @Bean
annotation.Bean.subTypeProperty() subtypes
. @Bean (filter=xxx)
with new @Transform
annotation.JsonSerializer
LAX mode now quotes reserved word attributes.
org.apache.juneau.transforms.DateSwap.ISO8601DTP
org.apache.juneau.transforms.DateSwap.ISO8601DTZP
Juno 5.0.0.30 is a minor update.
Bean.subTypes()
annotation in addition to subTypes
property.
Juno 5.0.0.31 is a moderate update.
Serializer
and Parser
class hierarchies.XMLGregorianCalendarSwap
to convert these to ISO8601 strings during serialization, and vice versa during parsing.
JsonParser
.
JsonParser.DEFAULT_STRICT
parser.
Juno 5.0.0.32 is a moderate update.
org.apache.juneau.dto.jsonschema
for information.
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.
Enums
through overriding toString()
and fromString()
on the enum class.Enum.valueOf()
to convert strings back into Enums
.JsonType
enum to be serialized to lowercase per the specification (e.g. Cognos
DTOs now have fluent-style bean setters.
Object
when the type is erased.
setFoo(Foo f)
, setFoo(Bar b)
), the BeanMap
API would sometime choose the wrong setter as the bean property setter. Accept
GET parameters with &Accept=text/json+simple
) wasn't working anymore.Accept
parameter is supposed to interpret spaces as &Accept=text/json%2Bsimple
.
Number
.Juno 5.0.0.33 is a moderate update.
WriterSerializer
class.
WriterSerializer s = new JsonSerializer();
addNotBeanClassPatterns(String...)
methods throughout API since these are now controlled by BeanContext.BEAN_notBeanPackages_add
/ BeanContext.BEAN_notBeanPackages_remove
properties.
RestServletProperties
.
RestServletProperties.REST_trimTrailingUriSlashes
RestRequest.getRequestURI(boolean trimTrailingSlashes)
method which is now redundant with this property.
RestServletProperties.REST_pathInfoBlankForNull
RestRequest.getPathInfo(boolean returnBlankForNull)
method which is now redundant with this property.
JsonSchemaMap
class for supporting linked schemas.
maxDepth
setting is reached, and will instead simply ignore content below the specified depth.RestServlet
. ?x-response-headers={Refresh=1}
HtmlDocSerializerContext.HTML_REFRESH
setting that added a Refresh meta tag to HTML documents, since this can now be controlled through X-Response-Headers
.
PhotosResource
now includes a default entry.
Juno 5.0.0.34 is a moderate update.
RestServlet.createRequestVarResolver(RestRequest)
for more information.
RestRequest
:
RestRequest.getVarResolver()
RestRequest.getServletURI()
RestRequest.getRequestParentURI()
RestResponse
:
RestResponse.sendRedirect(CharSequence)
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()
RestServletNls
to use ResourceDescription/MethodDescription
instead of RestResource/RestMethod
RestServletProperties.REST_htDocsFolder
.MessageFormat
(e.g. @Bean.stopClass
annotation for specifying stop classes for bean properties.
BeanFilter.setStopClass(Class)
which is the program equivalent to the annotation above.
ResultSetList
:
ResultSetList.handleBlob(Blob)
ResultSetList.handleClob(Clob)
Juno 5.0.0.35 is a minor update.
RestGuard.guard(RestRequest,RestResponse)
now returns a boolean to allow redirects to login pages.
Juno 5.0.0.36 is a minor update.
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. ClassMeta
that allowed the removal of
some synchronized blocks.
BeanContext.getClassMetaFromString(String)
.
Now supports primitive arrays such as StringUtils
and ClassUtils
.
Juno 5.1.0.0 is a major update.
HttpClient
that performs
serialization and parsing using Juno parsers, but leaves all the details of the HTTP connection
to the Apache code. org.apache.juneau.rest.client.jazz
package and org.apache.juneau.rest.client.jazz.JazzRestClient
class
for performing REST operations against Jazz servers.org.apache.juneau.urlencoding
package for details.
ExtendedReaderParser
abstract class and moved methods into
ReaderParser
class.
DataFormat
class from API since it was no longer necessary
due to API change above.
ParserStringReader
class.String
input.ParserReader
was enhanced to work
well with String
input, and tests show no significant performance differences.
org.apache.juneau.parser.Parser.parse(Object,int,ClassMeta)
convenience method added.
StringUtils
and ClassUtils
.
BeanContext.getClassMetaFromString(String)
."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
).
ClassMeta
.
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.
RestRequest
class.
RestRequest#getParameter(String,Class)
.
RestRequest.getMapParameter(String,Class,Class,Class)
and
RestRequest.getCollectionParameter(String,Class,Class)}
methods.
Juno 5.1.0.1 is a minor update.
@PathRemainder
.
pathInfo
on child resources.
Juno 5.1.0.2 is a minor update.
&Accept-Language
from being used as a GET parameter.
RestServletProperties.REST_allowMethodParam
to be disabled by default.
Juno 5.1.0.3 is a moderate update.
BeanContext.BEAN_beanConstructorVisibility
- Control which bean constructors are visible to Juno.
BeanContext.BEAN_beanClassVisibility
- Control which bean classes are interpreted as beans to Juno.
BeanContext.BEAN_beanFieldVisibility
- Control which fields are visible to Juno as bean properties.
BeanContext.BEAN_beanMethodVisibility
- Control which getters/setters are visible to Juno as bean properties.
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.
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.
@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.
@Json(wrapperAttr)
annotation that automatically wraps beans and objects in a wrapper
attribute when serializing to or parsing from JSON.
readProperty()
and writeProperty()
methods added to BeanFilter
class to allow individualized serialization and parsing behavior on a class-by-class basis.
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.
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.
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)
.
$A{...}
(request attributes) and $P{...}
(request parameters) to RestServlet.createRequestVarResolver(RestRequest)
.
Juno 5.1.0.4 is a minor update.
RestServlet.getPath()
method.
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.
BeanContext.addTransforms(Class[])
.
Previously, adding multiple conflicting filters resulted in random behavior.
Now filters are overridden when multiple matching filters are applied.
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).
Juno 5.1.0.5 is a moderate update.
Redirect
class that simplifies performing redirections in REST methods.
ResponseHandler
class and @RestResource(responseHandlers)
annotation
for defining customer response handlers for special kinds of POJOs.
UrlEncodingSerializer.serializeUrlPart(Object)
method.
RestRequest.getServletURIBuilder()
for construcing servlet-based URLs more efficiently.
RestResponse.getNegotiatedOutputStream()
that uses encoders if a match is found,
and RestResponse.getOutputStream()
that just return the underlying output stream without any modifications.
CoreObject.setProperties(ObjectMap)
on serializer and parser subclasses.
HtmlSerializer
where URL keys in Maps were not being serialized as hyperlinks.
JsonSerializer
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.
RestResponse.sendRedirect(...)
methods due to the introduction of the Redirect
class.
Juno 5.1.0.6 is a moderate update.
PojoSwap
.
Since it's rarely used, the beanContext
parameter was replaced with a PojoSwap#getBeanContext()
method on
the class.
PojoSwap
.
See SurrogateSwap
for details.
@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 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.
Juno 5.1.0.7 is a moderate update.
ParserContext.PARSER_debug
and SerializerContext.SERIALIZER_debug
.
settings for logging additional information for debugging problems.
SERIALIZER_ignoreRecursions
setting for explicitly ignoring recursions when
serializing models. Previously, the StackOverflowErrors
. When ResultSetList
for Oracle and SQL Server.
SerializerContext.getProperties()
and
ParserContext.getProperties()
.
SerializerContext
and ParserContext
since these are now available through context properties, and are typically not used.
XmlParser
now accepts application/xml
.
Traversable
that was causing it to be executed even if the servlet extra path info was empty.
Traversable
where it was not picking up filters and properties defined on REST Java methods.
Juno 5.1.0.8 is a moderate update, focused primarily on performance improvements.
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.
estimatedSize
parameter to the Parser
parse methods to
optimize buffering when the input size is known beforehand.
BeanContext
API to perform better in multi-threaded environments.
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.
RestClient#createHttpClient()
to allow customized subclasses to construct customized HTTP clients.
DefaultRestClient
class since it's now fully redundant with RestClient
.
RestClient.shutdown()
method for cleaning up the internal HTTP client when you're done using a REST client.
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.
org.apache.juneau
- Core serializers and parsers.
org.apache.juneau.rest
- REST server component.
org.apache.juneau.rest.client
- REST client component.
org.apache.juneau.rest.labels.Link
class moved to Link
.
org.apache.juneau.rest.RestException
in Encoder
class changed to IOException
.
RestClient.execute(HttpUriRequest)
method that allows subclasses to handle their own HTTP request execution.
JazzRestClient
to handle introduction of SSO support in v6.
&plainText
debug feature was broken.
RestRequest
.
Juno 5.1.0.10 is a moderate update.
UrlEncodingSerializer
and UrlEncodingParser
classes.
UonSerializer
and UonParser
classes.
BeanRuntimeExceptions
weren't being thrown on subsequent calls to BeanContext.getClassMeta(Class)
.
BeanContext.getPrimitiveDefault(Class)
to new ClassMeta.getPrimitiveDefault()
method for performance reasons.
BeanContext.addTransforms(Class[])
that would cause filter order to get messed up.
ClassMeta.newInstance()
can now create array instances.
HtmlSerializer
.
HtmlSerializer
where newlines were not being converted into line breaks.
WriterSerializer.toString(Object)
method that's identical to the serialize method but throws RuntimeExceptions
to make the serializer easier to use for debugging.
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.
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.
@QParam
and @HasQParam
annotations for accessing query parameters from the URL query string.
&plainText
parameter can now specify a false value.
RestServlet.onPreCall(RestRequest)
and RestServlet#onPostCall(RestRequest,RestResponse)
methods
since the properties are already accessible through RestRequest.getProperties()
.
UonSerializer
and UonParser
to serializer and parser lists on
BasicRestServlet
and RestServletJenaDefault
.
RestResponseEntity
to RestRequestEntity
.
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)
RestClient.shutdown()
to RestClient.close()
to mirror change in Apache API.
CodeFormatterResource
for quickly formatting Java and XML code samples in Javadocs.
UrlEncodedFormResource
for showing how to work with URL-Encoded form posts.
Juno 5.1.0.11 is a moderate update.
@Html
bean annotation.
@Html(noTables)
annotation that prevents
arrays/Collections from being serialized as tables.
@Html(noTableHeaders)
annotation that prevents
HTML tables from having header rows.
UonParser
.
UonParserContext.UON_whitespaceAware
property for controlling whether whitespace is ignored.
UrlEncodingContext.URLENC_expandedParams
property for controlling whether arrays/Collections
should be serialized/parsed as multi-part parameters.
@UrlEncoding(expandedParams)
annotation that specifies that bean properties of type array/Collection be serialized as multi-part parameters (e.g. &key=val1&key=val2
).
JsonSerializerContext.JSON_escapeSolidus
property for controlling whether slash characters should be escaped.
TeeOutputStream
and TeeWriter
classes.
ClassMeta.isInstance(Object)
method.
BeanMap.add(String,Object)
method.
Array properties are stored in a temporary list cache until BeanMap.getBean()
is called.
BeanPropertyMeta.add(BeanMap,Object)
method for adding values to Collection and array properties.
@Param(multipart)
and @Query(multipart)
annotations
for handling multi-part GET and POST parameters.
&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
.
¬race
must now be specified as &noTrace=true
.
RestRequest
for handling multi-part parameters:
RestRequest.getParameters(String,Class)
RestRequest#getQueryParameters(String,Class)
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.
ServletContext.getContextPath()
always ends with RestServletProperties.REST_allowMethodParam
is now BasicRestServlet
and RestServletJenaDefault
.
RestCall.allowRedirectsOnPosts(boolean)
.
RestCall.peekInputStream()
allows you to read response bodies without interrupting execution flow.
Session.toString()
now useful for debugging purposes.
Shows all request/response headers and bodies.
RestCallException
now includes HttpResponse
object for easier debugging.
RestClient.addListener(RestClientListener)
for registering request/response listeners.
RestClient.setClassLoader(ClassLoader)
method.
JazzRestClient
.
samples.ear
and samples.war
projects
have been replaced with an OSGi bundle with activated servlets in juno.samples
.
Juno 5.1.0.12 is a minor update.
ConfigFile.isEmpty()
method.
UonParser
to not treat ( ) , $ = ~
.
RestCallInterceptor
.
Allows responses to be inspected and modified before being processed.
Replaces RestClientListener
class.
Juno 5.1.0.13 is a minor update.
ClassMeta.newInstance()
method can now create new instances of arrays.
Link
are now serialized using UrlEncodingSerializer
, so arbitrary POJOs can now be passed as arguments.
org.apache.juneau.transforms.Datefilter.ISO8601DTZP
and org.apache.juneau.transforms.Datefilter.SimpleP
.
HtmlDocSerializerContext.HTMLDOC_nowrap
setting for HtmlDocSerializer
class.
Adds 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
.
UrlEncodingSerializer.serializeUrlPart(Object)
method.
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.
RestServletNls
class.
RestCall.setRedirectMaxAttempts(int)
method to prevent endless redirection loops.
RestCall#setRetryable(int,long,RetryOn)
method to automatically retry on failed connection attempts.
RestCallInterceptor.onRetry(RestCall,int,HttpRequest,HttpResponse)
method for listening in on retry attempts.
Juno 5.1.0.14 is a moderate update.
The major addition is support for
, the ability
to invoke server-side POJO methods through client-side proxy interfaces.
Remoteable Services
PojoIntrospector
class.
ClassUtils.getMethodSignature(Method)
method.
RestClient
for working with remoteable services:
RestClient.setRemoteableServletUri(String)
RestClient#getRemoteableProxy(Class)
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.
RestRequest
:
RestRequest.getParser()
RestRequest.getReaderParser()
Juno 5.1.0.15 is a minor update.
SerializerContext
:
SerializerContext.SERIALIZER_relativeUriBase
SerializerContext.SERIALIZER_absolutePathUriBase
SERIALIZER_uriAuthority
and SERIALIZER_uriContext
properties.
CsvSerializer
.
RestServletProperties
:
REST_defaultCharset
REST_servletURI
REST_relativeServletURI
RestCall
:
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...)
Juno 5.1.0.16 is a moderate update.
ClassMeta
that eliminates language-specific code in
the general class metadata.
ClassMeta.getXmlMeta()
ClassMeta.getJsonMeta()
ClassMeta.getHtmlMeta()
ClassMeta.getUrlEncodingMeta()
ClassMeta.getRdfMeta()
JsonType.ANY
enum.
@Html(asPlainText)
annotation.
HtmlDocSerializerContext.HTMLDOC_cssImports
property.
@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.
SerializerContext.SERIALIZER_sortCollections
and
SerializerContext.SERIALIZER_sortMaps
properties.
RestRequest.getServletParentURI()
method.
$R{servletParentURI}
variable.
ChildResourceDescriptions
.
Juno 5.1.0.17 is a major update.
BeanMap.get(Object)
and BeanMap.put(String,Object)
now
automatically performs filtering if filters are defined on the bean property or bean property class.
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.
RestResource.filters()
were being
interpreted as surrogate classes because they have hidden 1-arg constructors due to being inner classes.
MultiSet
where exception was being thrown if last set was empty.
ZipFileList
class for providing efficiently zipped directories through the REST interface.
RdfProperties.RDF_useXmlNamespaces
property.
XmlParserContext.XML_preserveRootElement
property.
ZipFileListResponseHandler
class.
"[ClassName].ResourceDescription"
is now "[ClassName].label"
.
"[ClassName].MethodDescription.[methodName]"
is now "[ClassName].[methodName]"
.
RestRequest
:
RestRequest.getQueryParameterMap()
RestRequest.getQueryParameterNames()
RestRequest.getPathInfoUndecoded()
RestRequest.getPathRemainderUndecoded()
RestRequest.getTrimmedRequestURI()
RestRequest.getTrimmedRequestURL()
RestRequest.getServletTitle()
RestRequest.getServletDescription()
RestRequest.getMethodDescription()
HttpServletRequestWrapper.getPathInfo()
to follow Servlet specs.
Returns RestRequest.getPathRemainder()
now automatically decodes the path remainder.
Use RestRequest.getPathRemainderUndecoded()
to get the unencoded path remainder.
RestRequest.getRequestParentURI()
when servlet is mapped to RestRequest.getServletURI()
when servlet is mapped to $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.
RestServlet.getDescription(RestRequest)
and RestServlet.getLabel(RestRequest)
.
BasicRestServlet
and RestServletJenaDefault
now provide default HTML titles
and descriptions:
BasicRestServlet
and RestServletJenaDefault
now provide default descriptions and back links:
and descriptions:
BasicRestServletGroup
class.
RestServletProperties.REST_trimTrailingUriSlashes
and RestServletProperties.REST_pathInfoBlankForNull
.
RestResource.label()
@RestResource(description)
@RestMethod(description)
RestMethod#responses()
Attr.description()
Content.description()
HasParam.description()
HasQParam.description()
Header.description()
Param.description()
QParam.description()
ChildResourceDescriptions
.
/tempDir/upload
showing how to use ServletFileUpload
with multipart form posts.
Juno 5.1.0.18 is a minor update affecting the server component only.
RestMethod.input()
and RestMethod.responses()
annotations.
These replace the various description
annotations added 2 days ago with a simpler design.
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).
MethodDescription
back to 5.1.0.16 since it was being used by someone.
Juno 5.1.0.19 is a minor update in terms of core functionality.
But it introduces a
project for building REST microservices and docker containers.
Microservices
ObjectMaps
.
See ObjectMap.include(String[])
and ObjectMap.exclude(String[])
methods.
@Html
annotations can now be applied to bean properties.
IOPipe
utility class.
StringVarResolver
. RestClient.doCallback(String)
method.
RestRequest.getHeaders()
method.
RestResponse.getUnbufferedWriter()
method.
x-response-headers
parameter from working correctly.
@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.
ResourceDescription.ResourceDescription(RestRequest,String,String)
constructor.
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
functionality.
ConfigFile
org.apache.juneau.config
API.
ConfigFile
is now thread safe and can be shared across multiple threads.
ConfigMgr
class for managing configuration files.
SimpleHtmlWriter
class.
Can be used for simple HTML DOM construction.
ProcBuilder
class for calling external processes.
ObjectMap.remove(Class,String,Object)
method.
HtmlDocSerializer
.
EncoderGroup#append(EncoderGroup)
method.
HtmlDocSerializerContext.HTMLDOC_addLinks
configuration property.
Parser.createContext(ObjectMap,Method,Object)
method.
Outer context objects can be passed in to create instances of non-static inner classes.
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. IOPipe
.
ReflectionUtils.getResource(Class,String)
method.
StringUtils.parseNumber(String,Class)
now returns zero for empty strings.
This affects the way most parsers handle blank values.
RestServlet
:
RestServlet.getConfig()
RestServlet.createConfigFile()
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.
RestServlet.handleNotFound(int,RestRequest,RestResponse)
method for customized handling
of when a resource or method was not found.
BasicRestServlet
now automatically processes RestServlet.handleNotFound(int,RestRequest,RestResponse)
method.
RestRequest
methods:
RestRequest.resolveVars(String)
RestRequest.getVarResource(String)
RestRequest.getConfig()
RestResponse
methods:
RestResponse.getDirectWriter(String)
.
RestResponse.getNegotiatedWriter()
.
getWriter()
now returns an unnegotiated writer.
getUnbufferedWriter()
has been removed.
@RestMethod(encoders)
and
RestMethod.inheritEncoders()
annotations.
Allows encoders to be fine-tuned at the method level.
@RestResource(config)
annotation for associating external ConfigFile
config files with servlets.
ResourceLink
.
org.apache.juneau.rest.matchers
package for commonly-used RestMatchers
:
Juno 5.2.0.0 is a major update. Major changes have been made to the microservice architecture and config INI file APIs.
org.apache.juneau.config
API.
ConfigFile
:
ConfigFile.getStringArray(String)
,ConfigFile.getStringArray(String,String[])
ConfigFile.getSectionAsBean(String,Class)
- Instantiate a new bean with property values in the specified section..
ConfigFile.writeProperties(String,Object,boolean,Class[])
- Copy the properties in a config file section into properties on an existing bean or POJO.
ConfigFile.getSectionMap(String)
- Get all the resolved values in a section.
ConfigFile.containsNonEmptyValue(String)
ConfigFile.isEncoded(String)
ConfigFile.addListener(ConfigFileListener)
- Listen for modification events on the config file.
ConfigFile.merge(ConfigFile)
- Merge the contents of another config file into this config file.
ConfigFile.getResolving()
, ConfigFile.getResolving(StringVarResolver)
- Return an instance of the config file that resolves string variables.
Much more efficient than the previous design since the same underlying config file object is shared.
ConfigFile.toWritable()
- Wraps the config file in a Writable
interface so that it can be serialized by the REST interface as a plain-text INI file instead of as a serialized POJO.
ConfigFile.getInt(String)
- Now supports ConfigMgr
:
ConfigMgr.create()
, ConfigMgr.create(Reader)
, ConfigMgr.create(File)
ConfigMgr.deleteAll()
Section
:
Section.setParent(ConfigFileImpl)
- Used by parsers to set the config file for this section.
Section.setName(String)
- Used by parsers to set the name for this section.
org.apache.juneau.config.ConfigFileListener
org.apache.juneau.config.SectionListener
org.apache.juneau.config.EntryListener
org.apache.juneau.config.Encoder
methods have access to field names to use them as salt values.
org.apache.juneau.config.XorEncoder
XOR key can be overridden through the fromString(String)
valueOf(String)
(e.g. enums)
parse(String)
(e.g. logging Level
class)
parseString(String)
forName(String)
(e.g. Class
and Charset
classes)
Pair<S,T>
and you try to parse into this
class (e.g. parser.parse(in, Pair.class )
), the unbound type variables
is interpreted as Object
instead of throwing an exception.
AtomicInteger
AtomicLong
BigInteger
BigDecimal
@NameProperty
and @ParentProperty
annotations are provided for identifying methods for setting names and parent POJOs on child POJOs.
For example, the config file Section
class represents a section
in a config file. It needs to know it's own name and have a link to the ConfigFile
that it belongs to. With these new annotations, config files can be reconstructed using any of the parsers.
Streamable
interface for identifying objects that can be serialized directly to an output stream.
Writable
interface for identifying objects that can be serialized directly to a writer.
StringObject
class that can be used for delayed object serialization.
ByteArrayCache
ByteArrayInOutStream
FileUtils
ThrowableUtils
StringVarMultipart
StringVarWithDefault
ObjectList
:
ObjectMap
:
ArrayUtils
:
IOUtils
:
IOUtils.pipe(Reader,Writer)
IOUtils.read(File)
IOUtils.readFile(String)
IOUtils.write(File,Reader)
PojoRest
:
PojoRest.get(Class,String,Object)
PojoRest.getString(String)
PojoRest.getString(String,String)
PojoRest.getInt(String)
PojoRest.getInt(String,Integer)
PojoRest.getLong(String)
PojoRest.getLong(String,Long)
PojoRest.getBoolean(String)
PojoRest.getBoolean(String,Boolean)
PojoRest.getMap(String)
PojoRest.getMap(String,Map)
PojoRest.getList(String)
PojoRest.getList(String,List)
PojoRest.getObjectMap(String)
PojoRest.getObjectMap(String,ObjectMap)
PojoRest.getObjectList(String)
PojoRest.getObjectList(String,ObjectList)
ProcBuilder
:
StringUtils
:
StringUtils.isEmpty(Object)
StringUtils.nullIfEmpty(String)
StringUtils.base64EncodeToString(String)
StringUtils.base64Encode(byte[])
StringUtils.base64DecodeToString(String)
StringUtils.base64Decode(String)
StringUtils.generateUUID(int)
StringUtils.trim(String)
StringUtils.parseISO8601Date(String)
StringUtils.replaceVars(String,Map)
StringUtils.pathStartsWith(String,String)
StringUtils.pathStartsWith(String,String[])
StringVar.doResolve(String)
method.
StringVarResolver.DEFAULT
field.
javax.mail.internet.MimeUtility
by implementing our own StringUtils.base64Encode(byte[])
method.
CalendarSwap
and DateSwap
classes now handle blank input better. Returns HtmlDocSerializer
specifies the default CSS location as /servletPath/style.css
instead of /servletPath/htdocs/juneau.css
.
This coincides with enhancements made in the server code for specifying styles.
HtmlDocSerializer
wraps output in two div tags instead of one (e.g. <div class='outerdata'><div class='data' id='data'>...</div></div>
).
Needed for supporting the new devops look-and-feel.
HtmlDocSerializer
.
RdfProperties.RDF_looseCollection
loose collections.
Parser
methods now check for SerializerGroup
and ParserGroup
ignores serializers and parsers if they throw NoClassDefFoundErrors
.
UrlEncodingParser
creates lists if the same attribute name is encountered more than once. Before it would just replace the previous value with the new value.
UrlEncodingSerializer.DEFAULT_SIMPLE_EXPANDED
serializer.
Args
:
getMainArg(int)
changed to Args.getArg(int)
.
Non-existent arguments are returned as Args.hasArg(int)
method.
org.apache.juneau.utils.CharsetUtils
class.
org.apache.juneau.utils.ConcurrentIdentityList
class.
MultiIterable
class.
PojoIntrospector
must now be instantiated with a ReaderParser
.
Simplifies the API on the class.
PojoRest
must now be instantiated with a ReaderParser
.
Simplifies the API on the class.
MessageBundle
and SafeResourceMultiBundle
moved from server component.
StringVarResolver
.
TeeWriter
and TeeOutputStream
.
AsciiSet
.
SerializerGroup
and ParserGroup
now ignores NoClassDefFoundErrors
so that resources that include Jena support can continue to operate even if the Jena libraries are not present.
FileUtils.createTempFile(String)
method.
PojoQuery
modified to handle bean getters that throw exceptions.
org.apache.juneau.rest.client.LaxRedirectStrategy
. Use HTTP Client equivalent.
RestCall
:
RestCall#addInterceptor(RestCallInterceptor)
RestCall.pipeTo(Writer)
RestCall.pipeTo(Writer,boolean)
RestCall.pipeTo(String,Writer,boolean)
RestCall.getWriter(String)
RestCall.pipeTo(OutputStream)
RestCall.pipeTo(OutputStream,boolean)
RestCall.pipeTo(String,OutputStream,boolean)
RestCall.getOutputStream(String)
RestCall.byLines()
RestCall.captureResponse()
RestCall.successPattern(String)
RestCall.failurePattern(String)
RestCall#addResponsePattern(ResponsePattern)
RestCall.run()
- Renamed from execute()
.
RestCall.getCapturedResponse()
RestCall.getResponsePojoRest(Class)
RestCall.getResponsePojoRest()
RestCall.logTo(Level,Logger)
RestCall.setConfig(RequestConfig)
RestCallInterceptor
:
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()
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.
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
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.
StreamResource
class.
REST Java methods can return instances of these to serialize OutputStreams
.
RestException
.
RestRequest
:
RestRequest.getReaderResource(String)
- Replaces getVarResource(String)
.
RestRequest.getReaderResource(String,boolean)
RestRequest.getReaderResource(String,boolean,String)
RestResponse
:
Content-Encoding: identity
when no encoding is used. Some clients don't interpret it correctly.
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()
JsoParser
from BasicRestServlet
and RestServletJenaDefault
.
These may represent a security risk if not handled correctly, so removed
them as a precaution.
RestServletProperties.REST_htDocsFolder
. Replaced with @RestResource(staticFiles)
.
@RestResource
.
RestResource.stylesheet()
RestResource.favicon()
@RestResource(staticFiles)
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.
consumes
and produces
fields instead of accept
and contentType
which was confusing.
properties
from OPTIONS pages.
ResourceLink.ResourceLink(String,RestRequest,String,Object[])
constructor.
StreamableHandler
- Allows REST Java methods to return instances of Streamable
.
WritableHandler
- Allows REST Java methods to return instances of Writable
.
RestUtils.trimPathInfo(StringBuffer,String,String)
method.
Microservice
class that serves as a generic
interface for microservices and their lifecycles.
RestMicroservice
class that implements a microservice
consisting of a REST interface.
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:
BasicRestServletJena
class if you want your REST interface to support RDF.
org.apache.juneau.microservice.RootResource
org.apache.juneau.microservice.SampleResource
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.
StringVarResolver
- New documentation.
Overview / Samples
- New section.
Juno 5.2.0.1 is a moderate update.
XmlSerializer
where ObjectList
:
ObjectList.getAt(Class,String)
ObjectList.putAt(String,Object)
ObjectList.postAt(String,Object)
ObjectList.deleteAt(String)
ObjectMap
:
ObjectMap.getAt(Class,String)
ObjectMap.putAt(String,Object)
ObjectMap.postAt(String,Object)
ObjectMap.deleteAt(String)
@ThreadSafe
annotation.
ClassFilter
class.
ConfigFile.getResolving(StringVarResolver,boolean)
method.
ConfigFile.getStringVar()
method.
ParserContext.PARSER_trimStrings
property.
SerializerContext.SERIALIZER_trimStrings
property.
Args.getStringVar()}
method.
ManifestFile
class
MessageBundle
class. Replaces StringMapVar
class.
StringVars
class with reusable common StringVar
instances.
JuneauLogger
class.
XmlParserContext.XML_trimWhitespace
changed to RestContext
:
RestClient
where the HTTP connection pool could end up exhausted if an error occurred.
RestClient
.
RestClient
is garbage collected without being closed:
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.
PropertyStore
class - Used for creating context objects.
Context
class - Read-only configurations for serializers and parsers.
Session
class - One-time use objects used by serializers and parsers.
org.apache.juneau.svl
.
StreamedVar
.
@Bean(typeName)
- Annotation that defines an identifying name for a bean class.
BeanFilterBuilder.typeName(String)
- Programmatic equivalent to annotation above.
BeanContext.BEAN_beanDictionary
- List of bean classes that make up the bean dictionary for lookup
during parsing.
BeanContext.BEAN_beanTypePropertyName
- The overridable type property name. Default is @BeanProperty(beanDictionary)
- Define a type dictionary
for a particular bean property value. This overrides the value specified using BeanContext.BEAN_beanDictionary
.
SerializerContext.SERIALIZER_addBeanTypeProperties
- Controls whether type properties are serialized.
@Bean(typeName)
value replaces the @Xml(name)
annotation, and the
BeanFilterBuilder
class.
Allows the BeanFilter
class to use final fields.
MessagePack
support.
Files
.
See Serializer.serialize(Object,Object)
Files
and other types.
See Parser.parse(Object,ClassMeta)
java.util.Date
).
org.apache.juneau.internal
package.
These internal utility classes are not meant for consumption outside the Juneau codebase.
Parser
:
org.apache.juneau.parser.Parser.createSession(ObjectMap,Method,Object)
Parser.getMediaRanges()
Serializer
:
org.apache.juneau.serializer.Serializer.createSession(ObjectMap,Method)
Serializer.getMediaRanges()
@Bean(sort)
annotation.
Class
objects to readable names via ClassUtils.getReadableClassName(Class)
.
ClassFilter
class since it's no longer needed.
SerializerGroup
and ParserGroup
.
BeanContext.convertToType(Object,Class)
.
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
.
BeanPropertyMeta
.
@Transform
annotation to @Pojo
so that it can be used for various POJO-related behavior, not just associating transforms.
Swagger DTOs
.
ResourceOptions
and related code.
@RestResource(title)
/ RestInfoProvider.getTitle(RestRequest)
@RestResource(description)
/ RestInfoProvider.getDescription(RestRequest)
@RestResource(termsOfService)
/ RestInfoProvider.getTermsOfService(RestRequest)
@RestResource(contact)
/ RestInfoProvider.getContact(RestRequest)
@RestResource(license)
/ RestInfoProvider.getLicense(RestRequest)
@RestResource(version)
/ RestInfoProvider.getVersion(RestRequest)
@RestResource(tags)
/ RestInfoProvider.getTags(RestRequest)
@RestResource(externalDocs)
/ RestInfoProvidergetExternalDocs(RestRequest)
@RestMethod(summary)
/ RestInfoProvider.getMethodSummary(String,RestRequest)
@RestMethod(description)
/RestInfoProvider.getMethodDescription(String,RestRequest)
@RestMethod(externalDocs)
@RestMethod(tags)
@RestMethod(deprecated)
@RestMethod(parameters)
@RestMethod(responses)
RestServletContext.paramFormat
context property.
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)
RestResource.clientVersionHeader()
- The name of the header used to identify the client version.
RestMethod.clientVersion()
- The client version range applied to a Java method.
JazzRestClient
class.
RestClient.setClientVersion(String)
.
Juneau 6.0.1 is a minor update.
ParserContext
.
ParserContext.PARSER_strict
ParserContext.PARSER_inputStreamCharset
ParserContext.PARSER_fileCharset
JsonParserContext.JSON_strictMode
. Replaced by PARSER_strict
.
byte[]
arrays can now be passed to Parser.parse(Object,Class)
for reader-based parsers.
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.
XmlFormat.ATTRS
format can now be applied to bean classes to have all bean properties serialized
as attributes instead of elements by default.
XmlFormat.ELEMENT
format can now be applied to bean properties to override the XmlFormat.ATTRS
setting above on specific bean properties.
XmlFormat.ELEMENTS
format can be applied to a bean property of type array/Collection to represent the child elements.
XmlFormat.MIXED
format can be applied to a bean property of type array/Collection to represent mixed content (text + child elements).
XmlFormat.MIXED_PWS
format. Identical to XmlFormat.TEXT
format can be applied to a bean property of a single object to represent a text node as a child.
XmlFormat.TEXT_PWS
format. Identical to XmlFormat.XMLTEXT
format that's identical to XmlFormat.TEXT
except
XML content is not escaped and serialized directly as the child content. The parser will reconvert this to the original XML text during parsing.
org.apache.juneau.xml
documentation.
XmlContentHandler
class.
XmlSerializer.DEFAULT
serializer now has namespaces disabled,
and XmlSerializer.DEFAULT_NS
has namespaces enabled. The 'XML-JSON' serializers have been eliminated.
addJsonTypeAttrs
and addJsonStringTypeAttrs
settings.
XMLEventReader
-based to XMLStreamReader
.
org.apache.juneau.html
documentation.
org.apache.juneau.dto.html5
.
BeanContext
class split into separate BeanContext
and BeanSession
classes.
SerializerContext
and ParserContext
now extend directly from BeanContext
.
SerializerSession
and ParserSession
now extend directly from BeanSession
.
BeanContext
:
BeanContext.BEAN_debug
- Debug setting. Replaces individual debug properties in the serializer and parser contexts.
BeanContext.BEAN_locale
- Specifies a default locale at the context level.
BeanContext.BEAN_timeZone
- Specifies a default timezone at the context level.
BeanContext.BEAN_mediaType
- Specifies a default media type at the context level.
parseMap()
, parseCollection()
)
by replacing them with two simple methods:
Parser.parse(Object,Class)
- Normal method.
Parser.parse(Object,Type,Type...)
- Method for parsing into parameterized maps and collections.
ClassMeta
object.
ClassMeta
objects.
parseMap()
and parseCollection()
methods!
BeanContext.normalizeClassMeta()
method.
PojoSwap
class. Now just two methods:
ClassMeta
class.
toObjectMap()
and fromObjectMap()/T(ObjectMap)
methods with
generalized swap(BeanSession)
/unswap(BeanSession,X)
/T(BeanSession,X)
methods.Swap methods
for information.
BeanSession.getMediaType()
method.
Allows for swaps and serializer/parser behavior to be tailored to individual media types.
Calendar
and Date
swaps:
CalendarSwap.ToString
,DateSwap.ToString
- To Strings
using the Date.toString()
method.
CalendarSwap.ISO8601DT
,DateSwap.ISO8601DT
- To ISO8601 date-time strings.
CalendarSwap.ISO8601DTZ
,DateSwap.ISO8601DTZ
- Same as CalendarSwap.ISO8601DTP
,DateSwap.ISO8601DTP
- Same as CalendarSwap.ISO8601DTPZ
,DateSwap.ISO8601DTPZ
- Same as CalendarSwap.RFC2822DT
,DateSwap.RFC2822DT
- To RFC2822 date-time strings.
CalendarSwap.RFC2822DTZ
,DateSwap.RFC2822DTZ
- Same as CalendarSwap.RFC2822D
,DateSwap.RFC2822D
- To RFC2822 date strings.
CalendarSwap.DateTimeSimple
,DateSwap.DateTimeSimple
- To simple CalendarSwap.DateSimple
,DateSwap.DateSimple
- To simple CalendarSwap.TimeSimple
,DateSwap.TimeSimple
- To simple CalendarSwap.DateFull
,DateSwap.DateFull
- To DateFormat.FULL
date strings.
CalendarSwap.DateLong
,DateSwap.DateLong
- To DateFormat.LONG
date strings.
CalendarSwap.DateMedium
,DateSwap.DateMedium
- To DateFormat.MEDIUM
date strings.
CalendarSwap.DateShort
,DateSwap.DateShort
- To DateFormat.SHORT
date strings.
CalendarSwap.TimeFull
,DateSwap.TimeFull
- To DateFormat.FULL
time strings.
CalendarSwap.TimeLong
,DateSwap.TimeLong
- To DateFormat.LONG
time strings.
CalendarSwap.TimeMedium
,DateSwap.TimeMedium
- To DateFormat.MEDIUM
time strings.
CalendarSwap.TimeShort
,DateSwap.TimeShort
- To DateFormat.SHORT
time strings.
CalendarSwap.DateTimeFull
,DateSwap.DateTimeFull
- To DateFormat.FULL
date-time strings.
CalendarSwap.DateTimeLong
,DateSwap.DateTimeLong
- To DateFormat.LONG
date-time strings.
CalendarSwap.DateTimeMedium
,DateSwap.DateTimeMedium
- To DateFormat.MEDIUM
date-time strings.
CalendarSwap.DateTimeShort
,DateSwap.DateTimeShort
- To DateFormat.SHORT
date-time strings.
SerializerGroup.getSerializerMatch(String)
that returns the matched serializer and media type.
ParserGroup.getParserMatch(String)
that returns the matched parser and media type.
EncoderGroup.getEncoderMatch(String)
that returns the matched encoder and encoding.
BeanDictionaryList
class can be used for defining reusable sets of bean dictionaries consisting
of classes annotated with @Bean(typeName)
.
BeanDictionaryMap
class can be used for defining reusable sets of bean dictionaries consisting
of classes not annotated with @Bean(typeName)
.
@Bean(beanDictionary)
annotation.
@BeanProperty(name)
annotation is used.
AtomBuilder
class.
org.apache.juneau.dto.atom
documentation.
MapSwap
and StringSwap
classes.
WriterSerializer.println(Object)
method. Useful for debugging purposes.
BeanContext.getClassMeta(Type,Type...)
and BeanSession.getClassMeta(Type,Type...)
methods for retrieving Map and Collection class metas.
Replaces the various getMapClassMeta()
/getCollectionClassMeta()
methods.
Juneau Data Transfer Objects (org.apache.juneau.dto)
UonParser.DEFAULT_WS_AWARE
and UrlEncodingParser.DEFAULT_WS_AWARE
parsers.
UonParser.DEFAULT
and UrlEncodingParser.DEFAULT
parsers will now handle whitespace.
UonParserContext.UON_whitespaceAware
configuration setting.
UonSerializer.DEFAULT_SIMPLE
, UonSerializer.DEFAULT_SIMPLE_ENCODING
and UrlEncodingSerializer.DEFAULT_SIMPLE
serializers since there is no separate simple mode anymore.
UonParserContext.UON_simpleMode
configuration setting.
OutputStreamSerializer.serializeToHex(Object)
method.
Parser.parse(Object,Class)
method can now
read the output from this method.
@Bean (subTypeProperty)
and @Bean (subTypes)
annotations
and replaced them with the ability to define subtypes using the existing @Bean(beanDictionary)
annotation on parent classes and interfaces.
SerializerContext.SERIALIZER_addBeanTypeProperties
setting is now enabled by default.
SERIALIZER_addIndentation
/JSON_addWhitespace
/UON_addWhitespace
properties into a single SerializerContext.SERIALIZER_useWhitespace
setting.
RestRequest
now passes locale and timezone to serializers/parsers/transforms.
RestRequest.getTimeZone()
method.
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...)
NameValuePairs
&plainText=true
specified.
Juneau 6.2.0 is a major update.
ConfigFileBuilder
.
Lockable
interface.
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
org.apache.juneau.uon
package.
XmlFormat.VOID
format to identify HTML void elements.
style()
override methods to all elements.
SwaggerBuilder
class.
here
and in the VarResolver
.
$IF
variable for if-else block logic.
$SWITCH
variable for switch block logic.
HtmlParser
can now parse full body contents generated by HtmlDocSerializer
.
MsgPackParser
to allow it to be used in remoteable proxies.
@Bean(typePropertyName)
annotation allows you to
specify the name of the SerializerContext.SERIALIZER_abridged
.
org.apache.juneau.remoteable
for all remoteable proxy interface annotations.
6 - Remoteable Services
6.1 - Interface proxies against 3rd-party REST interfaces
UrlEncodingSerializerContext.URLENC_paramFormat
.
UrlEncodingSerializerBuilder
:
UrlEncodingSerializerBuilder.paramFormat(String)
UrlEncodingSerializerBuilder.plainTextParams()
@RestResource
annotation can now be applied to
any class! You're no longer restricted to subclassing your resources from RestServlet
.
RestServlet
should have an equivalent for non-RestServlet
classes.
RestServlet
.
Child resources do not.
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.
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.
RestServlet
classes must have one of the following to allow it to be instantiated:
public T(RestConfig)
constructor.
public T()
constructor.
RestResourceResolver
for instantiating it.
RestServlet
classes can optionally include the following init methods to gain access to the config and context:
public init(RestConfig)
public init(RestContext)
@RestResource
to allow non-RestServlet
resources to do the same as subclassing directly from RestServlet
:
resourceResolver()
- Specify a RestResourceResolver
class for resolving child resources.
callHandler()
- Specify a RestCallHandler
class for handling the lifecycle of a REST call.
infoProvider()
- Specify a RestInfoProvider
class for customizing title/description/Swagger information on a REST resource.
logger()
- Specify a RestLogger
class for handling logging.
@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)
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.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.
@RestMethod (name="PROXY" )
annotation on REST methods.
Used to expose interface proxies without the need for RemoteableServlet
.
@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 RestClient
class doX(Object url)
methods now handle HttpClient URIBuilder
instances.
RestClient
:
RestClient.getRemoteableProxy(Class,Object)
- For interface proxies defined using @RestMethod (name="PROXY" )
.
RestClient.getRemoteableProxy(Class,Object,Serializer,Parser)
- Same as above, but overrides the serializer and parser defined on the client.
doPost(Object)
doCall(HttpMethod,Object,Object)
- Can now pass in instances of NameValuePairs
for easy form posts.
RestCall
:
uri(Object)
query(String,Object,boolean,PartSerializer)
query(String,Object)
queryIfNE(String,Object)
query(Map)
queryIfNE(Map)
query(String)
formData(String,Object,boolean,PartSerializer)
formData(String,Object)
formDataIfNE(String,Object)
formData(Map)
formDataIfNE(Map)
header(String,Object,boolean,PartSerializer)
header(String,Object)
headerIfNE(String,Object)
headers(Map)
headersIfNE(Map)
host(String)
port(int)
userInfo(String,String)
userInfo(String)
scheme(String)
RestClientBuilder
:
executorService(ExecutorService,boolean)
paramFormat(ExecutorService,boolean)
RestClientBuilder.plainTextParams()
noTrace()
- Adds a No-Trace: true
header on all requests to prevent
the servlet from logging errors.
debug()
now adds a Debug: true
header on all requests.
RestCall
:
runFuture()
getResponseFuture(Class)
getResponseFuture(Type,Type...)
getResponseAsStringFuture()
serializer(Serializer)
- Override the serializer defined on the client for a single call.
parser(Parser)
- Override the parser defined on the client for a single call.
input(Object)
- Now accepts instances of NameValuePairs
.
getResponse(Class)
- Can now pass in any of the following:
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.
NameValuePairs
:
append(String,Object)
append(String,Object,PartSerializer)
RetryOn
is now an abstract class with an additional method:
0
s to try a random port.
RestMicroservice
class:
getPort()
getURI()
Microservice
class for easier method chaining.
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.http
.
@BeanProperty(name)
.
2.8 - Virtual Beans
2.13 - Comparison with Jackson
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)
ConfigFile.getSectionAsInterface(String,Class)
.
@BeanProperty
annotation can now be applied to getters
and setters defined on interfaces.
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)
org.apache.juneau.serializer.PartSerializer
interface particularly tailored to HTTP
headers, query parameters, form-data parameters, and path variables.
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
pages=
links=
@URI
.
SerializerContext.SERIALIZER_uriContext
SerializerContext.SERIALIZER_uriRelativity
SerializerContext.SERIALIZER_uriResolution
SerializerContext.SERIALIZER_maxIndent
@BeanProperty(value)
.
UonSerializer.UON_paramFormat
,
and the UON/URL-Encoding serializers will now always serialize all values as plain text.
SerializerListener
SerializerBuilder.listener(Class)
@RestResource(serializerListener)
RestConfig.serializerListener(Class)
ParserListener
ParserBuilder.listener(Class)
@RestResource(parserListener)
RestConfig.parserListener(Class)
RestClientBuilder.listeners(Class,Class)
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.
@Html(render)
annotation and HtmlRender
class that allows you
to customize the HTML output and CSS style on bean properties:
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
HtmlDocTemplate
that allows full control over rendering
of HTML produced by HtmlDocSerializer
.
@NameProperty
and @ParentProperty
can now be applied to fields.
BeanContext
:
@BeanProperty(format)
.
RestRequest
class functionality has been broken up into the following
functional pieces to reduce its complexity:
RestRequest.getBody()
- The request body.
RestRequest.getHeaders()
- The request headers.
RestRequest.getQuery()
- The request query parameters.
RestRequest.getFormData()
- The request form data parameters.
RestRequest.getPathMatch()
- The path variables and remainder.
RestRequest
- The request object.
HttpServletRequest
- The superclass of RestRequest
.
RestResponse
- The response object.
HttpServletResponse
- The superclass of RestResponse
.
Accept
AcceptCharset
AcceptEncoding
AcceptLanguage
Authorization
CacheControl
Connection
ContentLength
ContentType
Date
Expect
From
Host
IfMatch
IfModifiedSince
IfNoneMatch
IfRange
IfUnmodifiedSince
MaxForwards
Pragma
ProxyAuthorization
Range
Referer
TE
UserAgent
Upgrade
Via
Warning
TimeZone
InputStream
ServletInputStream
Reader
OutputStream
ServletOutputStream
Writer
ResourceBundle
- Client-localized resource bundle.
MessageBundle
- A resource bundle with additional features.
Locale
- Client locale.
RequestHeaders
- API for accessing request headers.
RequestQuery
- API for accessing request query parameters.
RequestFormData
- API for accessing request form data.
RequestPath
- API for accessing path variables.
RequestBody
- API for accessing request body.
HttpMethod
- The method name matched (when using @RestMethod (name="*" )
)
Logger
- The logger to use for logging.
JuneauLogger
- Logger with additional features.
RestContext
- The resource read-only context.
Parser
- The parser matching the request content type.
Swagger
- The auto-generated Swagger doc.
ConfigFile
- The external config file for the resource.
@RestResource(paramResolvers)
that allows you to define your own custom Java method parameter resolvers.
RestResponse.getWriter()
was not being flushed automatically
at the end of the HTTP call.
@RestMethod
:
defaultQuery()
defaultFormData()
bpIncludes()
bpExcludes()
@Header(def)
- Default header value.
@Query(def)
- Default query parameter value.
@FormData(def)
- Default form data parameter value.
@RestResource
:
@RestMethod
:
RestConfig
:
setHtmlTitle(String)
setHtmlDescription(String)
setHtmlBranding(String)
setHtmlHeader(String)
setHtmlLinks(String)
setHtmlNav(String)
setHtmlAside(String)
setHtmlFooter(String)
setHtmlCss(String)
setHtmlCssUrl(String)
setHtmlNoWrap(boolean)
setHtmlNoResultsMessage(String)
setHtmlTemplate(Class)
setHtmlTemplate(HtmlDocTemplate)
addWidget(Class)
RestResponse
:
setHtmlTitle(Object)
setHtmlDescription(Object)
setHtmlBranding(Object)
setHtmlHeader(Object)
setHtmlLinks(Object)
setHtmlNav(Object)
setHtmlAside(Object)
setHtmlFooter(Object)
setHtmlCss(Object)
setHtmlCssUrl(Object)
setHtmlNoWrap(boolean)
setHtmlNoResultsMessage(Object)
setHtmlTemplate(Class)
setHtmlTemplate(HtmlDocTemplate)
&plainText=true
parameter now works on byte-based serializers by converting the output to hex.
Widget
PoweredByJuneauWidget
ContentTypeLinksColumnWidget
ContentTypeLinksRowWidget
QueryWidget
devops.css
cleaned up.
RestRequest
.
These all have equivalents in RestRequest.getUriContext()
.
org.apache.juneau.remoteable.Path
annotation for specifying path variables on remoteable interfaces.
@RequestBean
annotation for specifying beans with remoteable annotations
defined on properties.
NameValuePairs
and beans as input
when using 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
Juneau 6.3.1 is a minor release.
PojoQuery
improvements.
RemoteMethod.returns()
annotation.
BeanContext.BEAN_includeProperties
and BeanContext.BEAN_excludeProperties
settings.
HtmlDocSerializerContext
:
HTMLDOC_script
HTMLDOC_style
- Was HTMLDOC_stylesheet
- Was ResourceFinder
utility class.
Allows you to search for resources up the parent hierarchy chain.
Also allows you to search for localized resources.
HtmlDocSerializerContext
:
Var
implementations can now throw exceptions and will be converted to
navlinks()
- Now an array of strings instead of a JSON object. Simplified syntax.
Widget
API.
@HtmlDoc(widgets)
instead of separately on Widget.getName()
now defaults to the simple class name.
PoweredByApacheWidget
-> PoweredByApache
PoweredByJuneauWidget
-> PoweredByJuneau
MenuItemWidget
can be used as a starting point for creatint pull-down menu items.
ContentTypeMenuItem
widget that provides a pull-down menu
with hyperlinks for all supported languages for that page:
QueryMenuItem
widget that provides a pull-down menu
of a search/view/order-by/page form:
ThemeMenuItem
widget that provides a pull-down menu
with hyperlinks to show the content in the default stylesheets:
@HtmlDoc
:
style()
- Renamed from css()
.
stylesheet()
- Renamed from cssUrl()
.
script()
- Add arbitrary Javascript to page header.
@HtmlDoc(nowrap)
so that the setting only applies
to the data contents, not the whole page.
RestRequest
:
@RestResource(stylesheet)
annotation.
It's no longer needed now that you can easily specify styles via @HtmlDoc(header)
:
title()
description()
branding()
BasicRestServlet
class defines the following default header
that can be easily overridden:
htmldoc=
$F
variable resolver for resolving the contents of
files in the classpath.
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=
ReaderResource.toCommentStrippedString()
method.
bpIncludes()
and bpExcludes()
annotations on $R
variable: 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"
:
Category | Maven Artifacts | Description | Prereqs |
---|---|---|---|
Juneau Core | juneau-marshall | Serializers and parsers for:
|
|
juneau-marshall-rdf |
Serializers and parsers for:
|
|
|
juneau-dto |
Data Transfer Objects for:
|
|
|
juneau-svl | Simple Variable Language API |
|
|
juneau-config | Configuration file API |
|
|
Juneau REST | juneau-rest-server | REST Servlet API |
|
juneau-rest-server-jaxrs | Optional JAX-RS support |
|
|
juneau-rest-client | REST Client API |
|
|
Juneau Microservice | juneau-microservice-server | REST Microservice Server API |
|
juneau-microservice-template | Developer template project |
|
|
Examples | juneau-examples-core |
Core code examples | |
juneau-examples-rest |
REST code examples | ||
Juneau All | juneau-all |
Combination of the following:
|
|
@Swap
annotation.
@Pojo
and @BeanProperty(swap)
annotations.
@Swaps
annotation for defining multiple swaps
against the same POJO when they're differentiated by media types:
Surrogate
interface for identifying surrogate classes.
StringBuilders
.
Readers
and InputStreams
directly to the output stream or writer.
PojoSwaps
, this can be used to provide customized
output for specific content types.
SerializerSession
and ParserSession
objects are now reusable if used within the same thread.
PojoSwap.swap(BeanSession,Object)
and PojoSwap.unswap(BeanSession,Object,ClassMeta)
can now throw arbitrary exceptions instead of having to wrap them in SerializeException
/ParseException
.
CalendarUtils
class that encapsulates serialization/parsing logic from CalendarSwap
and
DateSwap
.
Html.anchorText()
.
ObjectList
:
ObjectMap
:
PojoRest
:
BeanSession.getMediaType()
wasn't returning a value.
getClass()
to retrieve the annotation value could not be called before calling
the super ()
method.
PojoMerge
HtmlElementMixed.children(Object...)
can now take in collections
of objects.
toString()
method.
Swagger.toString()
produces JSON and the HTML5 Form.toString()
produces HTML.
@RestHook
annotation.
RestServlet.init(ServletConfig)
method is now final and can
no longer be extended.
HookEvent.INIT
or
HookEvent.POST_INIT
for initialization.
RestServlet
have been removed:
init(RestConfig)
- Use HookEvent.INIT
instead.
onSuccess(RestRequest, RestResponse, long)
- Use HookEvent.END_CALL
instead.
onPreCall(RestRequest)
- Use HookEvent.PRE_CALL
instead.
onPostCall(RestRequest, RestResponse)
- Use HookEvent.POST_CALL
instead.
MenuItemWidget
.
MenuItemWidget.getContent(RestRequest)
that
can return raw HTML via readers or char-sequences, or any other object (such as HTML5 beans) that will
get converted to HTML using HtmlSerializer.DEFAULT
.
RestResourceResolver
instances are now inherited from parent resources to child resources
unless explicitly overridden at the child level.
@RestResource
:
resourceResolver()
RestResource.contextPath()
-
allowHeaderParams()
-
RestContext.REST_allowHeaderParams
setting.
RestResource.allowMethodParam()
-
RestContext.REST_allowMethodParam
setting.
allowBodyParam()
-
RestContext.REST_allowBodyParam
setting.
renderResponseStackTraces()
-
RestContext.REST_xxx
setting.
useStackTraceHashes()
-
RestContext.REST_useStackTraceHashes
setting.
defaultCharset()
-
RestContext.REST_defaultCharset
setting.
RestResource.paramFormat()
-
RestContext.REST_paramFormat
setting.
@RestMethod
:
defaultCharset()
-
RestContext.REST_defaultCharset
setting.
RestMethod.paramFormat()
-
RestContext.REST_paramFormat
setting.
Tooltip
?stylesheet
query parameter.
RestServletJenaDefault
class to remove the Jena dependency class on
the juneau-rest-server
artifact.
BasicRestServlet
and add the RDF serializers and
parsers.
jetty.xml
file
for maximum flexibility instead of the hodge-podge of support in the config file.
jetty.xml
file.
RestMicroservice
:
addServlet(Servlet,String)
addServletAttribute(String,Object)
getServer()
getInstance()
getPort()
getContextPath()
getProtocol()
getHostName()
Microservice
:
JettyLogger
for directing Jetty logging to the
java.util.logging framework.
DebugResource
for viewing and generating
Jetty thread dumps through REST calls.
This release ups the Java prerequisite to Java 7.
HttpMethodName
with valid static string HTTP method names.
org.apache.juneau.dto.Link
renamed to LinkString
.
Helps avoid confusion since there are other Link classes in the library.
@HtmlDoc (links)
renamed to navlinks
.
@HtmlDoc(head)
.
@HtmlDoc (favIcon)
.
@HtmlDoc (head)
, you can define them using:
head={
RestResponse/RestConfig/RestContext
classes and moved it into the new HtmlDocBuilder
class.
This release is a minor update. It includes the following prereq updates:
create()
methods for builders on serializers and parsers.
SerializerGroup.create()
ParserGroup.create()
EncoderGroup.create()
RestClient.create()
ConfigFile.create()
SerializerSession.serialize(Object,Object)
has been change to match Serializer.serialize(Object,Object)
.
Var
class to restrict when nested and embedded variables
are resolved.
@RestResource(maxInput)
and
@RestMethod(maxInput)
for alleviating
potential DoS attacks.
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.
Microservice
startConsole()
createConsoleCommands()
getConsoleReader()
getConsoleWriter()
Version 7.1.0 is a major update with major implementation refactoring across all aspects of the product.
Context
classes (e.g. JsonSerializerContext
) have been folded into
their respective serializer or parser classes (e.g. JsonSerializer
).
JsonSerializer
is now:
All Context
objects are thread-safe and read-only.
JsonSerializerSession
is now:
Session objects are transient objects that live for the duration of a single parse.
JsonSerializerBuilder
is now:
Builder objects are used for building up and creating Context
objects.
PropertyStore
class has been completely rewritten.
It is now a read-only configuration store build using the PropertyStoreBuilder
class.
PropertyStore
class was overly-complicated with many read/write
locks to ensure thread-safety.
PropertyStore
objects
that can be used as hash keys.
PartSerializer
/PartParser
classes
have been replaced with the following all located in the new org.apache.juneau.httppart
package:
org.apache.juneau.httppart
HttpPartType
HttpPartSerializer
UonPartSerializer
SimpleUonPartSerializer
SimplePartSerializer
HttpPartParser
UonPartParser
SimplePartParser
ContextBuilder.property(String,Object)
renamed to ContextBuilder.set(String,Object)
.
ResourceFinder
class has been replaced with the following:
SerializerSession
:
ParserSession
:
Parser.PARSER_unbuffered
setting allows you to disable internal
buffering on the JSON and UON parsers so that they can be used to read continous streams of objects.
JsonParser.JSON_validateEnd
and UonParser.UON_validateEnd
settings allow you to control whether we validate that there is no garbage at the end of the parsed input.
Parser.PARSER_autoCloseStreams
setting allows input streams and
readers passed into parsers to be automatically closed after parsing.
Surrogate
classes.
@Swap
annotation can now be used with
Surrogate
classes.
RestServletDefault
renamed to BasicRestServlet
.
RestServletGroupDefault
renamed to BasicRestServletGroup
.
RequestAttributeVar
, first non-null value returned by HttpServletRequest.getAttribute(String)
.
RequestFormDataVar
, first non-null value returned by RestRequest.getFormData(String)
.
RequestHeaderVar
, first non-null value returned by RestRequest.getHeader(String)
.
RestInfoVar
, first non-null value returned by RestRequest.getInfoProvider()
.
Info.getContact()
RestInfoProvider.getDescription(RestRequest)
Swagger.getExternalDocs()
Info.getLicense()
RestInfoProvider.getMethodDescription(Method,RestRequest)
RestInfoProvider.getMethodSummary(Method,RestRequest)
RestInfoProvider.getSiteName(RestRequest)
Swagger.getTags()
Info.getTermsOfService()
RestInfoProvider.getTitle(RestRequest)
Info.getVersion()
RequestPathVar
, first non-null value returned by RestRequest.getPath(String)
.
RequestQueryVar
, first non-null value returned by RestRequest.getQuery(String)
RequestVar
, first non-null other request variable.
RestRequest.getContextPath()
RestRequest.getMethod()
RestRequest.getMethodDescription()
RestRequest.getMethodSummary()
HttpServletRequestWrapper.getPathInfo()
UriContext.getRootRelativePathInfoParent()
HttpServletRequestWrapper.getRequestURI()
RestRequest.getResourceDescription()
RestRequest.getResourceTitle()
UriContext.getRootRelativeServletPathParent()
RestRequest.getServletPath()
UriContext.getRootRelativeServletPath()
RestRequest.getSiteName()
RestConfig
class into RestContextBuilder
.
RestContext
objects can now be set declaratively through the
following new properties:
REST_allowHeaderParams
REST_allowBodyParam
REST_allowedMethodParams
REST_renderResponseStackTraces
REST_useStackTraceHashes
REST_defaultCharset
REST_maxInput
REST_paramResolvers
REST_converters
REST_guards
REST_responseHandlers
REST_defaultRequestHeaders
REST_defaultResponseHeaders
REST_produces
REST_consumes
REST_clientVersionHeader
REST_resourceResolver
REST_logger
REST_callHandler
REST_infoProvider
REST_path
REST_contextPath
REST_staticFiles
REST_staticFileResponseHeaders
REST_classpathResourceFinder
REST_useClasspathResourceCaching
REST_widgets
REST_mimeTypes
@RestResource(staticFiles)
has been simplified, and
now allows you to specify response headers in the strings.
REST_staticFileResponseHeaders
.
REST_useClasspathResourceCaching
.
REST_classpathResourceFinder
RestMatcherReflecting
class.
RestMatcher
that has a public constructor that
takes in the server and method arguments.
@RestResource.allowMethodParam
renamed to RestResource.allowedMethodParams()
.
@RestMethod.serializersInherit
and @RestMethod.parsersInherit
replaced with
simplified @RestMethod(inherit)
.
RequestFormData
:
addDefault(Map)
takes in a
Map<String,Object>
instead of Map<String,String>
.
RequestHeaders
:
addDefault(Map)
takes in a
Map<String,Object>
instead of Map<String,String>
.
RequestQuery
:
addDefault(Map)
takes in a
Map<String,Object>
instead of Map<String,String>
.
RestContext
:
getResource(String,Locale)
renamed to getClasspathResource(String,Locale)
getResourceAsString(String,Locale)
renamed to getClasspathResourceAsString(String,Locale)
getResource(Class,MediaType,String,Locale)
renamed to getClasspathResourceAsString(Class,MediaType,String,Locale)
getClasspathResource(Class,String,Locale)
.
getClasspathResourceAsString(Class,String,Locale)
.
getClasspathResource(Class,Class,MediaType,String,Locale)
.
getDefaultRequestHeaders
returns a
Map<String,Object>
instead of Map<String,String>
.
getDefaultRequestHeaders
returns a
Map<String,Object>
instead of Map<String,String>
.
RestRequest
:
getSupportedMediaTypes()
replaced with
getConsumes()
and
getProduces()
.
getReaderResource(String,boolean,MediaType)
renamed to
getClasspathReaderResource(String,boolean,MediaType)
getReaderResource(String,boolean)
renamed to
getClasspathReaderResource(String,boolean)
getReaderResource(String)
renamed to
getClasspathReaderResource(String)
@RestResource
:
mimeTypes()
annotation.
@RestMethod
:
consumes()
and
produces()
for overriding the supported media types inferred from the serializers and parsers.
RestCallHandler
split up into RestCallHandler
and
BasicRestCallHandler
RestInfoProvider
split up into RestInfoProvider
and
BasicRestInfoProvider
RestLogger
split up into RestLogger
,
BasicRestLogger
and NoOpRestLogger
RestResourceResolverSimple
renamed to BasicRestResourceResolver
@Messages
and @Properties
REST java method parameter
annotations.
MessageBundle
and
RestRequestProperties
as unannotated parameters.
RestInfoProvider
class.
ReaderResourceBuilder
StreamResourceBuilder
RestResponse.getNegotiatedOutputStream()
now returns a
FinishableServletOutputStream
and RestResponse.getNegotiatedWriter()
now returns a FinishablePrintWriter
that allows you to finish the output
without closing the stream.
DefaultHandler
class now calls finish()
instead of close()
on the stream.
BasicRestServlet
class
(which were previously defined on the Resource
class):
RestClient.RESTCLIENT_query
and
builder method RestClientBuilder.query(String,Object)
.
PartSerializer
with HttpPartSerializer
.
SimpleUonPartSerializer
which will
serialize strings as plain-text and collections/arrays as comma-delimited lists.
RestCall
class:
RestCall
and RestClient
now implement the Closeable
interface.
Resource
and ResourceGroup
classes removed.
BasicRestServlet
and BasicRestServletGroup
can be used instead.
ResourceJena
and ResourceJenaGroup
classes renamed to
BasicRestServletJena
and BasicRestServletJenaGroup
.
7.2.1 is a major release that introduces several significant new features:
org.apache.juneau.http.annotation
package.
RemoteInterface
- Used for remote proxy interfaces served up through
RemoteInterfaceServlet
or REST RemoteResource
- Used for 3rd-party REST interfaces.
@Query ("*" )
, @FormData ("*" )
, @Header ("*" )
, @Path ("*" )
RestRequest.getRequest(RequestBeanMeta)
method.
@Bean (typeName)
was not being detected on non-bean POJO classes.
@BeanProperty (name)
but forget to
add it to your @Bean (properties)
annotation.
@Html (asXml)
and @Html (asPlainText)
replaced with
@Html(format)
.
@Html (format=XML )
.
SERIALIZER_addRootType
SERIALIZER_addBeanTypes
and is disabled by default.
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---
Parser.PARSER_debugOutputLines
for controlling how many input lines are added to the exception message above.
BeanContext.BEAN_useEnumNames
for controlling whether enums are serialized
using their name or the toString()
method.
BeanContext.BEAN_examples
for defining examples of POJOs.
@Example
annotation for defining examples of POJOs.
getX()
and isX()
method, the getX()
method takes precedence.
@JsonSchema
annotation.
NullPointerException
when serializing beans with a dyna-property (i.e. @Bean ("*" )
)
which returns a @Bean ("*" )
) using a method that returns a collection of extra keys.
BeanProperty.name()
@Html(format)
annotation:
HtmlFormat.HTML_CDC
- Format collections as comma-delimited lists.
HtmlFormat.HTML_SDC
- Format collections as space-delimited lists.
JsonSerializer.Simple
is ObjectMaps
and ObjectLists
.
JsonSerializer.Simple
class has been moved into the top-level SimpleJsonSerializer
class.
RdfSerializer.Xml
-> RdfXmlSerializer
RdfSerializer.XmlAbbrev
-> RdfXmlAbbrevSerializer
RdfSerializer.N3
-> N3Serializer
RdfSerializer.NTriple
-> NTripleSerializer
RdfSerializer.Turtle
-> TurtleSerializer
RdfParser.Xml
-> RdfXmlParser
RdfParser.N3
-> N3Parser
RdfParser.NTriple
-> NTripleParser
RdfParser.Turtle
-> TurtleParser
SchemaInfo.required(Object...)
was defined as a boolean
instead of a list of strings.
new Select().disabled(true )
will produce <select disabled='disabled'>
@RestResource(swagger)
and @RestMethod(swagger)
annotations.
UriResolver
when request path info had special characters.
text/html+schema
instead of text/html
for schema documents).
RemoteableServlet
class has been moved and renamed to RemoteInterfaceServlet
.
RemoteInterfaceServlet
now provides a form page for invoking remote interface methods in a browser.
@HtmlDoc (script)
when serialized which could cause script lines to become commented out.
@Response
annotation that can be applied to
throwables thrown from REST methods and POJOs returned by REST methods to specify non-200 status return codes and descriptions in Swagger documentation.
@Path ("/*" )
to access the path remainder which includes all the new OpenAPI parsing support.
org.apache.juneau.rest.helper
BeanDescription
ChildResourceDescriptions
ReaderResource
ReaderResourceBuilder
SeeOtherRoot
ResourceDescription
StreamResource
StreamResourceBuilder
org.apache.juneau.rest.exception
BadRequest
Conflict
ExpectationFailed
FailedDependency
Forbidden
Gone
HttpVersionNotSupported
InsufficientStorage
InternalServerError
LengthRequired
Locked
LoopDetected
MethodNotAllowed
MisdirectedRequest
NetworkAuthenticationRequired
NotAcceptable
NotExtended
NotFound
NotImplemented
PayloadTooLarge
PreconditionFailed
PreconditionRequired
RangeNotSatisfiable
RequestHeaderFieldsTooLarge
ServiceUnavailable
TooManyRequests
Unauthorized
UnavailableForLegalReasons
UnprocessableEntity
UnsupportedMediaType
UpgradeRequired
UriTooLong
VariantAlsoNegotiates
@HtmlDoc(nav)
and @HtmlDoc(navlinks)
can now both be used on the same annotation.
nav()
are free-form HTML that gets rendered immediately after the navigation links.
ReaderParser
- The reader parser matching the request content type.
InputStreamParser
- The input stream parser matching the request content type.
$F
variable can now be used as a initialization time variable.
AtomFeedResource
example pulls a bean example from a file on the classpath:
$F
variable to retrieve localized versions of files (since you're not within
the scope of a client request.
RestResource.nowrap()
annotation has been changed to a string with a default value of Path.name()
annotation parameter is now required.
@RestMethod (inherit)
annotation has been removed and replaced with the following classes:
RestResource.serializers()
RestResource.parsers()
RestResource.beanFilters()
RestResource.pojoSwaps()
RestMethod.serializers()
RestMethod.parsers()
RestMethod.beanFilters()
RestMethod.pojoSwaps()
Inherit
class.
RequestPathMatch
class has been renamed to RequestPath
.
@Request
objects can now be used as parameters in RestRequest
:
MenuItemWidget
to allow population of menu item content using Javascript and Ajax calls:
Widget
to allow retrieving classpath resources with embedded SVL variables:
RestMethod.name()
and RestMethod.path()
have changed.
RedirectToServletRoot
class has been renamed to SeeOtherRoot
.
Accept
and Content-Type
headers:
RestCall.execute()
method.
RestCall.run()
.
RestCall.input(Object)
method renamed to RestCall.body(Object)
to match OpenAPI terminology.
RestClient
and RestClientBuilder
protected so that they can be subclassed.
RestClient.getRemoteableProxy()
methods have been split into separate methods for Remote Interfaces and Remote Resources:
RestClient
RestClient.getRemoteInterface(Class)
RestClient.getRemoteInterface(Class,Object)
RestClient.getRemoteInterface(Class,Object,Serializer,Parser)
RestClient.getRemoteResource(Class)
RestClient.getRemoteResource(Class,Object)
RestClient.getRemoteResource(Class,Object,Serializer,Parser)
files
:
files
directory in the working directory,
and you have access to modify the CSS theme files.
SwaggerUI.css
file controls the look-and-feel of the Swagger UI, so you can make
modification there as well.
BasicRestConfig
interface (which defines the default settings for the BasicRestServlet
class)
now looks like this...
PoweredByApache
widget which used to serve as a page footer has been eliminated.
This release contains mostly bug fixes. Code changes have been made to preserve binary backwards compatibility with 7.1.0.
@JsonSchema
annotation has been merged with the @Schema
annotation.
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.
ResolvingReaderResource
class has been added that includes the variable-resolving support since
this relies on the juneau-svl
package.
RemoteInterfaceServlet
class has been renamed to RrpcServlet
.
@RestMethod (name="PROXY" )
has been changed to @RestMethod (name="RRPC" )
.
RestClient.getRemoteInterface()
method has been renamed to RestClient.getRrpcInterface(Class)
.
@RemoteMethod (path)
values containing '/' characters were erroneously being encoded.
This release contains minor bug fixes and general improvements to the PetStore sample application.
This release cleans up deprecated APIs from the 7.2.0 release and makes significant modifications to the Microservice APIs.
The project structures of the REST, Microservice, and Examples have been modified to fit new Spring Boot integration support. The structure is now as follows:
juneau-rest
juneau-rest-client
juneau-rest-server
juneau-rest-server-jaxrs
juneau-rest-server-rdf
juneau-rest-server-springboot
- New Spring Boot integration support classes.
juneau-microservice
juneau-microservice-core
- New. Contains base Microservice
class.
juneau-microservice-jetty
- New. Contains new JettyMicroservice
class.
juneau-my-jetty-microservice
- New. Template starter project for Jetty-based microservices.
juneau-my-springboot-microservice
- New. Template starter project for Spring-Boot-based microservices.
juneau-examples
juneau-core
juneau-microservice-rest
- Now contains only servlet example classes. No Jetty configuration.
juneau-microservice-rest-jetty
- Servlet examples deployed using Jetty.
juneau-microservice-rest-springboot
- Servlet examples deployed using Spring Boot.
RestServlet
:
Microservice
class and console support.
MicroserviceListener
API for defining lifecycle event listeners.
ConfigCommand
class for performing config queries and updates through
the microservice console.
JettyMicroservice
class replaces the previous RestMicroservice
.
app.json
and Procfile
files for deploying examples into Heroku.
Copyright © 2018 Apache. All rights reserved.