Apache Juneau Overview
- A universal toolkit for marshalling POJOs to a wide variety of content types using a common framework.
- A universal REST server API for creating Swagger-based self-documenting REST interfaces using POJOs, simply deployed as one or more top-level servlets in any Servlet 3.1 or above container.
- A universal REST client API for interacting with Juneau or 3rd-party REST interfaces using POJOs and proxy interfaces.
- A sophisticated configuration file API.
- A REST microservice API that combines all the features above with a simple configurable Jetty server for creating lightweight stand-alone REST interfaces that start up in milliseconds.
- Built on top of Servlet and Apache HttpClient APIs that allow you to use the newest HTTP/2 features such as request/response multiplexing and server push.
Table of Contents
1 - Introduction
Juneau is a single cohesive framework consisting of the following parts:
- A universal toolkit for marshalling POJOs to a wide variety of content types using a common framework.
- A universal REST server API for creating Swagger-based self-documenting REST interfaces using POJOs, simply deployed as one or more top-level servlets in any Servlet 3.1 or above container.
- A universal REST client API for interacting with Juneau or 3rd-party REST interfaces using POJOs and proxy interfaces.
- A sophisticated configuration file API.
- A REST microservice API that combines all the features above with a simple configurable Jetty server for creating lightweight stand-alone REST interfaces that start up in milliseconds.
- Built on top of Servlet and Apache HttpClient APIs that allow you to use the newest HTTP/2 features such as request/response multiplexing and server push.
Questions via email to dev@juneau.apache.org are always welcome.
Juneau is packed with features that may not be obvious at first. Users are encouraged to ask for code reviews by providing links to specific source files such as through GitHub. Not only can we help you with feedback, but it helps us understand usage patterns to further improve the product.
History
Juneau started off as a popular internal IBM toolkit called Juno. Originally used for serializing POJOs to and from JSON, it later expanded in scope to include a variety of content types, and then later REST servlet, client, and microservice APIs. It's use grew to more than 50 projects and was one of the most popular community source projects within IBM.
In June of 2016, the code was donated to the Apache Foundation under the project
1.1 - Features
- KISS is our mantra! No auto-wiring. No code generation. No dependency injection. Just add it to your classpath and use it. Extremely simple unit testing!
- Enjoyable to use
- Tiny - ~1MB
- Exhaustively tested
- Lots of up-to-date documentation and examples
- Minimal library dependencies:
- juneau-marshall, juneau-dto, juneau-svl, juneau-config - No external dependencies. Entirely self-contained.
- juneau-marshall-rdf - Optional RDF support. Requires Apache Jena 2.7.1+.
- juneau-rest-server - Any Servlet 3.1.0+ container.
- juneau-rest-client - Apache HttpClient 4.5+.
- juneau-microservice - Eclipse Jetty.
- Built on top of Servlet and Apache HttpClient APIs that allow you to use the newest HTTP/2 features such as request/response multiplexing and server push.
1.2 - Components
We've strived to keep prerequisites to an absolute minimum in order to make adoption as easy as possible.
The library consists of the following artifacts found in the Maven group "org.apache.juneau":
| Category | Maven Artifacts | Description | Prerequisites |
|---|---|---|---|
| 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-examples | juneau-examples-core | Core code examples | |
| juneau-examples-rest | REST code examples | ||
| juneau-all | juneau-all |
Combination of the following:
|
|
Each component are also packaged as stand-alone OSGi modules.
2 - juneau-marshall
Maven Dependency
Java Library
juneau-marshall-7.2.0.jar
OSGi Module
org.apache.juneau.marshall_7.2.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.
2.1 - Serializers
One of the goals of Juneau was to make serialization as simple as possible. In a single line of code, you should be able to serialize and parse most POJOs. Despite this simplicity, Juneau provides lots of extensibility and configuration properties for tailoring how POJOs are serialized and parsed.
The built-in serializers in Juneau are fast, efficient, and highly configurable. They work by serializing POJOs directly to streams instead of using intermediate Document Object Model objects.
In most cases, you can serialize objects in one line of code by using one of the default serializers:
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).
2.2 - Parsers
Parsers work by parsing input directly into POJOs instead of having to create intermediate Document Object Models. This allows them to parse input with minimal object creation.
Like the serializers, you can often parse objects in one line of code by using one of the default parsers:
The parsers can also be used to populating existing bean and collection objects:
-
In the example above, we're parsing "lax" JSON (single quotes, unquoted attributes).
The JSON parser can handle any valid JSON syntax (such as quoted or unquoted attributes, single or double
quotes).
It can also handle JSON fragments and embedded Javascript comments. Many of the JSON examples provided will use lax syntax which is easier to read since we don't have to deal with escapes.
2.3 - SerializerGroups and ParserGroups
Above the serializers and parsers are the SerializerGroup and
ParserGroup classes.
These classes allow serializers and parsers to be retrieved by W3C-compliant HTTP Accept
and Content-Type values...
The REST servlet API builds upon the SerializerGroup and ParserGroup classes
to provide annotated REST servlets that automatically negotiate the HTTP media types and allow the developer
to work with requests and responses as POJOs.
2.4 - ObjectMap and ObjectList
The ObjectMap and ObjectList classes are generic Java
representations of JSON objects and arrays.
These classes can be used to create "unstructured" models for serialization (as opposed to "structured"
models consisting of beans).
If you want to quickly generate JSON/XML/HTML from generic maps/collections, or parse JSON/XML/HTML into
generic maps/collections, these classes work well.
These classes extend directly from the following JCF classes:
The
These object can be serialized in one of two ways:
-
Using the provided
ObjectMap.serializeTo(java.io.Writer)orObjectList.serializeTo(java.io.Writer)methods. -
Passing them to one of the
Serializerserialize methods. -
Simply calling the
ObjectMap.toString()orObjectList.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:
-
As a general rule, if you do not specify a target type during parsing, or if the target type cannot be
determined through reflection, the parsers automatically generate
ObjectMaps andObjectLists .
2.5 - Configurable Properties
Serializers and parsers have a wide variety of configurable properties.
They all extend from the BeanContextBuilder class that allows you to easily construct
new instances from scratch or build upon existing instances.
For example, the following code shows how to configure a JSON serializer:
WriterSerializer s = JsonSerializer
.
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.
2.5.1 - Common Properties
All serializers and parsers extend from the BeanContext class.
Therefore, the following properties are common to all serializers and parsers:
BeanContextBEAN_beanClassVisibilityBEAN_beanConstructorVisibilityBEAN_beanDictionaryBEAN_beanFieldVisibilityBEAN_beanFiltersBEAN_beanMapPutReturnsOldValueBEAN_beanMethodVisibilityBEAN_beansRequireDefaultConstructorBEAN_beansRequireSerializableBEAN_beansRequireSettersForGettersBEAN_beansRequireSomePropertiesBEAN_beanTypePropertyNameBEAN_debugBEAN_excludePropertiesBEAN_ignoreInvocationExceptionsOnGettersBEAN_ignoreInvocationExceptionsOnSettersBEAN_ignorePropertiesWithoutSettersBEAN_ignoreUnknownBeanPropertiesBEAN_ignoreUnknownNullBeanPropertiesBEAN_implClassesBEAN_includePropertiesBEAN_localeBEAN_mediaTypeBEAN_notBeanClassesBEAN_notBeanPackagesBEAN_pojoSwapsBEAN_propertyNamerBEAN_sortPropertiesBEAN_timeZoneBEAN_useInterfaceProxiesBEAN_useJavaBeanIntrospector
2.5.2 - Common Serializer Properties
In addition to the common properties above, the following properties are common to all serializers:
SerializerSERIALIZER_abridgedSERIALIZER_addBeanTypePropertiesSERIALIZER_detectRecursionsSERIALIZER_ignoreRecursionsSERIALIZER_initialDepthSERIALIZER_listenerSERIALIZER_maxDepthSERIALIZER_maxIndentSERIALIZER_quoteCharSERIALIZER_sortCollectionsSERIALIZER_sortMapsSERIALIZER_trimEmptyCollectionsSERIALIZER_trimEmptyMapsSERIALIZER_trimNullPropertiesSERIALIZER_trimStringsSERIALIZER_uriContextSERIALIZER_uriRelativitySERIALIZER_uriResolutionSERIALIZER_useWhitespace
2.5.3 - Common Parser Properties
In addition to the common properties above, the following properties are common to all parsers:
2.6 - Contexts, Builders, Sessions, and PropertyStores
All the serializers, parsers, and REST server/client classes use the following design pattern:
-
Context - A thread-safe read-only object.
Examples:BeanContext,JsonSerializer -
ContextBuilder - A thread-safe builder for contexts.
Examples:BeanContextBuilder,JsonSerializerBuilder -
Session - A non-thread-safe single-use object with configuration combined from context and runtime args such as locale/timezone and overridden properties.
These are created byContextobjects.
Examples:BeanSession,JsonSerializerSession -
PropertyStore - A thread-safe read-only set of configuration properties.
EachContextcontains onePropertyStore. -
PropertyStoreBuilder - A thread-safe builder forPropertyStoreobjects.
EachContextBuildercontains onePropertyStoreBuilder.
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:
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.
2.7 - Transforms
By default, the Juneau framework can serialize and parse a wide variety of POJOs out-of-the-box.
However, two special classes are provided tailor how certain Java objects are handled by the framework.
These classes are:
BeanFilter- Transforms that alter the way beans are handled.PojoSwap- Transforms that swap non-serializable POJOs with serializable POJOs during serialization (and optionally vis-versa during parsing).StringSwap- Convenience subclass for swaps that convert objects to strings.MapSwap- Convenience subclass for swaps that convert objects to maps.
Transforms are added to serializers and parsers (and REST clients) using the following configuration properties:
Annotations are also provided for specifying transforms directly on classes and methods (all described in later sections):
-
@Swap- Used to tailor how non-bean POJOs get interpreted by the framework. -
@Bean- Used to tailor how beans get interpreted by the framework. -
@BeanConstructor- Maps constructor arguments to property names on beans with read-only properties. -
@BeanIgnore- Ignore classes, fields, and methods from being interpreted as bean or bean components. -
@BeanProperty- Used to tailor how bean properties get interpreted by the framework. -
@NameProperty- Identifies a setter as a method for setting the name of a POJO as it's known by its parent object. -
@ParentProperty- Identifies a setter as a method for adding a parent reference to a child object. -
@URI- Used to identify a class or bean property as a URI.
2.7.1 - PojoSwaps
PojoSwaps are a critical component of Juneau.
They allow the serializers and parsers to handle Java objects that wouldn't normally be serializable.
Swaps are, simply put, 'object swappers' that swap in serializable objects for non-serializable ones during serialization, and vis-versa during parsing.
Some examples of non-serializable POJOs are File, Reader,
Iterable, etc...
These are classes that aren't beans and cannot be represented as simple maps, collections, or primitives.
In the following example, we introduce a PojoSwap that will swap in ISO8601 strings for
Date objects:
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
The following example shows the BASE64 swap in use:
Several PojoSwaps are already provided for common Java objects:
org.apache.juneau.transforms
In particular, the CalendarSwap and
DateSwap transforms provide a large number of customized swaps to
ISO, RFC, or localized strings.
Swaps have access to the session locale and timezone through the BeanSession.getLocale() and
BeanSession.getTimeZone() methods.
This allows you to specify localized swap values when needed.
If using the REST server API, the locale and timezone are set based on the Accept-Language and
Time-Zone headers on the request.
-
The 'swapped' class type must be a serializable type.
See the definition for Category 4 objects in POJO Categories.
2.7.2 - Per-media-type PojoSwaps
Swaps can also be defined per-media-type.
The PojoSwap.forMediaTypes() method can be overridden to
provide a set of media types that the swap is invoked on.
It's also possible to define multiple swaps against the same POJO as long as they're differentiated
by media type.
When multiple swaps are defined, the best-match media type is used.
In the following example, we define 3 swaps against the same POJO. One for JSON, one for XML, and one for all other types.
2.7.3 - One-way PojoSwaps
In the previous sections, we defined two-way swaps, meaning swaps where the original objects could be
reconstructing during parsing.
However, there are certain kinds of POJOs that we may want to support for serializing, but that are not
possible to reconstruct during parsing.
For these, we can use one-way object swaps.
A one-way POJO swap is simply an object transform that only implements the swap() method.
The unswap() method is simply left unimplemented.
An example of a one-way swaps would be one that allows Iterators to be serialized as JSON arrays.
It can make sense to be able to render Iterators as arrays, but in general it's not possible to
reconstruct an Iterator during parsing.
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.
2.7.4 - @Swap Annotation
@Swap can be used to associate a swap class using an
annotation.
This is often cleaner than using the builder pojoSwaps() method since you can keep
your swap class near your POJO class.
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
2.7.5 - Templated Swaps
The @Swap.template() annotation allows you to associate
arbitrary contextual strings with swaps.
The primary purpose is for providing template names, such as for Apache FreeMarker, therefore
the name 'template'.
However, the usage of the string is open-ended.
For example, you could pair a template string like so:
The implementation of the FreeMarker swap would look something like this:
2.7.6 - Swap Methods
Various methods can be defined on a class directly to affect how it gets serialized.
This can often be simpler than using PojoSwaps.
Objects serialized as Strings can be parsed back into their original objects by
implementing one of the following methods on the class:
-
public static T fromString(String)
Any of the following method names also work:valueOf(String)parse(String)parseString(String)forName(String)forString(String)
-
public T(String)
Note that these methods cover conversion from several built-in Java types, meaning the parsers can automatically construct these objects from strings:
fromString(String)-UUIDvalueOf(String)-Boolean,Byte,Double,Float,Integer,Long,Short,Date,Time,Timestampparse(String)-DateFormat,MessageFormat,NumberFormat,Date,LevelparseString(String)-DatatypeConverterforName(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)Xis 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)Xis the swap class type.public T(X)Xis the swap class type.
The following shows how our form template class can be modified to allow the parsers to reconstruct our original object:
2.7.7 - Surrogate Classes
Surrogate classes are very similar in concept to PojoSwaps except they're simpler to define.
For example, let's say we want to be able to serialize the following class, but it's not serializable for some reason (for example, there are no properties exposed):
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.
See Also:
2.7.8 - @Bean Annotation
The @Bean annotation is used to tailor how beans are
interpreted by the framework.
Bean property inclusion and ordering on a bean class can be done using the
@Bean.properties() annotation.
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.
2.7.9 - @BeanProperty Annotation
The @BeanProperty annotation is used to tailor how
individual bean properties are interpreted by the framework.
The @BeanProperty.name() annotation
is used to override the name of the bean property.
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
This is similar in concept to the Jackson
The primary purpose is for backwards compatibility in parsing newer streams with addition
information into older beans.
The following shows various ways of using dynamic bean properties.
Similar rules apply for value types and swaps.
The property values optionally can be any serializable type or use swaps.
-
Note that if you're not interested in these additional properties, you can also use the
BeanContext.BEAN_ignoreUnknownBeanPropertiessetting 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:
- Beans - Only render the specified properties of the bean.
- Maps - Only render the specified entries in the map.
- Bean/Map arrays - Same, but applied to each element in the array.
- Bean/Map collections - Same, but applied to each element in the collection.
The @BeanProperty.format()
annotation specifies a String format for converting a bean property value to a formatted string.
2.7.10 - @BeanConstructor Annotation
The @BeanConstructor annotation is used to
map constructor arguments to property names on bean with read-only properties.
Since method parameter names are lost during compilation, this annotation essentially redefines
them so that they are available at runtime.
The definition of a read-only bean is a bean with properties with only getters, like shown below:
Beans can also be defined with a combination of read-only and read-write properties.
2.7.11 - @BeanIgnore Annotation
The @BeanIgnore annotation is used to
ignore classes, fields, and methods from being interpreted as beans or bean components.
When applied to classes, objects will be converted to strings even though they look like beans.
When applied to fields and getters/setters, they will be ignored as bean properties.
2.7.12 - @NameProperty Annotation
The @NameProperty annotation is used to
identify a setter as a method for setting the name of a POJO as it's known by its parent object.
A commonly-used case is when you're parsing a JSON map containing beans where one of the bean properties is the key used in the map.
2.7.13 - @ParentProperty Annotation
The @ParentProperty annotation is used to
identify a setter as a method for adding a parent reference to a child object.
A commonly-used case is when you're parsing beans and a child bean has a reference to a parent bean.
Parsers will automatically set this field for you in the child beans.
2.7.14 - POJO Builders
Juneau parsers can use builders to instantiate POJOs.
This is useful in cases where you want to create beans with read-only properties.
Note that while it's possible to do this using the @BeanConstructor
annotation, using builders can often be cleaner.
A typical builder usage is shown below:
MyBean b = MyBean.
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:
- A way to detect and instantiate a builder using reflection.
- A way to instantiate a POJO from a builder.
The first can be accomplished through any of the following:
- A static
create()method on the POJO class that returns a builder instance.public static MyBuildercreate () {...} - A public constructor on the POJO class that takes in a single parameter that implements the
Builderinterface.
The builder class must have a public no-arg constructor.public MyPojo(MyBuilder b) {...} - A
@Builderannotation on the POJO class.
The builder class must have a public no-arg constructor.@Builder (MyBuilder.class )public class MyPojo {...}
The second can be accomplished through any of the following:
- The existence of a
build()method on the builder class.public MyPojo build() {...} - The existence of a public constructor on the POJO class that takes in the builder instance.
public MyPojo(MyBuilder b) {...}
See Also:
2.7.15 - URIs
Juneau serializers have sophisticated support for transforming relative URIs to absolute form.
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
Setting that defines the URI contextual information used to resolve relative URIs.Serializer.SERIALIZER_uriRelativity
Setting that defines how relative URIs should be interpreted.
Possible values:UriRelativity.RESOURCE
Relative URIs should be considered relative to the servlet URI.
(e.g."http://host:port/context-root/servlet-path" ).UriRelativity.PATH_INFO
Relative URIs should be considered relative to the request URI.
(e.g."http://host:port/context-root/servlet-path/path-info" ).
Serializer.SERIALIZER_uriResolution
Setting that defines the final format of serialized URIs.
Possible values:UriResolution.ABSOLUTE
Resolve to an absolute URL.
(e.g."http://host:port/context-root/servlet-path/path-info" ).UriResolution.ROOT_RELATIVE
Resolve to a root-relative URL.
(e.g."/context-root/servlet-path/path-info" ).UriResolution.NONE
Don't do any URL resolution.
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:
2.7.16 - BeanFilter Class
The BeanFilter class is the programmatic equivalent to the
@Bean annotation.
In practice, it's usually simpler to use the @Bean and
@BeanProperty annotations on your bean classes.
However, bean filters make it possible to accomplish the same when you can't add annotations
to existing code.
Bean filters are defined through BeanFilterBuilders.
In the previous examples, we defined this bean annotation:
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.
2.7.17 - Interface Filters
Occasionally, you may want to limit bean properties to only those defined on a parent class or interface.
This is accomplished through interface filters.
Interface filters are defined through the following:
For example, let's define the following interface and implementation:
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.
2.7.18 - Stop Classes
Whereas interface filters limit properties defined on child classes, stop filters do the opposite and limit properties defined on parent classes.
Stop classes are defined through the following:
Stop classes are identical in purpose to the stop class specified by Introspector.getBeanInfo(Class, Class).
Any properties in the stop class or in its base classes will be ignored during serialization.
For example, in the following class hierarchy, instances of C3 will include property p3,
but not p1 or p2.
2.7.19 - Bypass Serialization using Readers and InputStreams
Juneau serializers treat instances of Readers and InputStreams special by
simply serializing their contents directly to the output stream or writer.
This allows you to embed fully customized serializer output.
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:
- Due to the nature of the RDF serializers, Readers and InputStreams are serialized as literals, not as RDF text. This is due to the fact that the RDF serializers use a DOM for serialization, so we don't have access to the underlying stream.
2.8 - Bean Names and Dictionaries
While parsing into beans, Juneau attempts to determine the class types of bean properties through
reflection on the bean property getter or setter.
Often this is insufficient if the property type is an interface or abstract class that cannot be
instantiated.
This is where bean names and dictionaries come into play.
Bean names and dictionaries are used for identifying class types when they cannot be inferred through reflection.
Bean classes are given names through the @Bean.typeName()
annotation.
These names are then added to the serialized output as virtual
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:
- Any bean class that specifies a value for
@Bean.typeName(). - Any subclass of
BeanDictionaryListcontaining a collection of bean classes with type name annotations. - Any subclass of
BeanDictionaryMapcontaining a mapping of type names to classes without type name annotations. - Any array or collection of the objects above.
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.
- Type names do not need to be universally unique. However, they must be unique within a dictionary.
-
The following reserved words cannot be used as type names:
object, array, number, boolean, null. -
Serialized type names are DISABLED by default.
They must be enabled on the serializer using the
Serializer.SERIALIZER_addBeanTypePropertiesconfiguration property.
2.8.1 - Bean Subtypes
In addition to the bean type name support described above, simplified support is provided for bean subtypes.
Bean subtypes are similar in concept to bean type names, except for the following differences:
- You specify the list of possible subclasses through an annotation on a parent bean class.
- You do not need to register the subtype classes on the bean dictionary of the parser.
In the following example, the abstract class has two subclasses:
When serialized, the subtype is serialized as a virtual
JsonSerializer s = JsonSerializer.
The following shows what happens when parsing back into the original object.
JsonParser p = JsonParser.
2.9 - Virtual Beans
The BeanContext.BEAN_useInterfaceProxies setting (enabled by default) allows
the Juneau parsers to parse content into virtual beans (bean interfaces without implementation classes).
For example, the following code creates an instance of the specified unimplemented interface:
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.
2.10 - Non-Tree Models and Recursion Detection
The Juneau Serializer API is designed to be used against POJO tree structures.
It expects that there not be loops in the POJO model (e.g. children with references to parents, etc...).
If you try to serialize models with loops, you will usually cause a StackOverflowError to
be thrown (if Serializer.SERIALIZER_maxDepth is not reached
first).
If you still want to use the Juneau serializers on such models, Juneau provides the
Serializer.SERIALIZER_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:
{ b: { c: { } } }
Without recursion detection enabled, this would cause a stack-overflow error.
Recursion detection introduces a performance penalty of around 20%.
For this reason the setting is disabled by default.
2.11 - Parsing into Generic Models
The Juneau parsers are not limited to parsing back into the original bean classes.
If the bean classes are not available on the parsing side, the parser can also be used to
parse into a generic model consisting of Maps, Collections, and primitive
objects.
You can parse into any Map type (e.g. HashMap, TreeMap), but
using ObjectMap is recommended since it has many convenience methods
for converting values to various types.
The same is true when parsing collections. You can use any Collection (e.g. HashSet,
LinkedList) or array (e.g. Object[], String[],
String[][]), but using ObjectList is recommended.
When the map or list type is not specified, or is the abstract Map, Collection,
or List types, the parser will use ObjectMap and ObjectList by
default.
For example, given the following JSON:
{
id:
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.
2.12 - Reading Continuous Streams
The following parsers can be configured to read continuous streams of objects from the same input stream:
The JsonParser and UonParser
classes can read continuous streams by using the Parser.PARSER_unbuffered
setting.
This prevents the parsers from using an internal buffer that would read past the end of the currently
parsed POJO.
Examples:
Note that this isn't perfect in all cases since you can't combine two JSON numbers into a single
reader (e.g. "123" + "456" = "123456").
For obvious reasons, do not use the following properties when reading continuous streams:
The MsgPackParser class doesn't use any internal buffering to begin with, so it can be used with
continuous streams without any special properties.
2.13 - Comparison with Jackson
Juneau was developed independently from Jackson, but shares many of the same features and capabilities. Whereas Jackson was created to work primarily with JSON, Juneau was created to work for multiple languages. Therefore, the terminology and annotations in Juneau are similar, but language-agnostic.
The following charts describe equivalent features between the two libraries:
Annotations
| 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.
|
2.14 - POJO Categories
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 |
-
Serializers are designed to work on tree-shaped POJO models.
These are models where there are no referential loops (e.g. leaves with references to nodes, or nodes
in one branch referencing nodes in another branch).
There is a serializer setting
detectRecursionsto look for and handle these kinds of loops (by setting these references tonull ), but it is not enabled by default since it introduces a moderate performance penalty.
2.15 - JSON Details
Juneau supports converting arbitrary POJOs to and from JSON using ultra-efficient serializers and parsers.
The JSON serializer converts POJOs directly to JSON without the need for intermediate DOM objects using a
highly-efficient state machine.
Likewise, the JSON parser creates POJOs directly from JSON without the need for intermediate DOM objects.
The following example shows JSON for a typical bean:
Sample Beans
Sample Code
Person p =
Normal JSON
{
Lax JSON
{
name:
2.15.1 - JSON Methodology
The JSON data type produced depends on the Java object type being serialized.
- Primitives and primitive objects are converted to JSON primitives.
- Beans and Maps are converted to JSON objects.
- Collections and arrays are converted to JSON arrays.
- Anything else is converted to JSON strings.
Data type conversions:
| POJO type | JSON type | Example | Serialized form |
|---|---|---|---|
| String | String | serialize( |
|
| 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
2.15.2 - JSON Serializers
The JsonSerializer class is used to serialize POJOs into JSON.
The JSON serializer provides the following settings:
The following pre-configured serializers are provided for convenience:
2.15.3 - JSON Parsers
The JsonParser class is used to parse JSON into POJOs.
The JSON parser provides the following settings:
The following pre-configured parsers are provided for convenience:
The JSON parser supports ALL valid JSON, including:
- Javascript comments.
- Single or double quoted values.
- Quoted (strict) or unquoted (non-strict) attributes.
- JSON fragments (such as string, numeric, or boolean primitive values).
- Concatenated strings.
2.15.4 - @Json Annotation
The @Json(wrapperAttr) annotation
can be used to wrap beans inside a JSON object with a specified attribute name.
The annotation can be applied to beans as well as other objects serialized to other types (e.g. strings).
Example:
The following shows the JSON representation with and without the annotation present:
| Without annotation | With annotation |
|---|---|
|
{
name: |
{
personBean: {
name: |
2.15.5 - JSON-Schema Support
Juneau provides the JsonSchemaSerializer class for generating JSON-Schema
documents that describe the output generated by the JsonSerializer class.
This class shares the same properties as JsonSerializer.
For convenience the JsonSerializer.getSchemaSerializer() method has been
added for creating instances of schema serializers from the regular serializer instance.
Note: As of this writing, JSON-Schema has not been standardized, so the output generated by the schema serializer may be subject to future modifications.
Sample Beans
The code for creating our POJO model and generating JSON-Schema is shown below:
JSON Schema
{
type:
2.16 - XML Details
Juneau supports converting arbitrary POJOs to and from XML using ultra-efficient serializers and parsers.
The XML serializer converts POJOs directly to XML without the need for intermediate DOM objects.
Likewise, the XML parser uses a STaX parser and creates POJOs directly without intermediate DOM objects.
Unlike frameworks such as JAXB, Juneau does not require POJO classes to be annotated to produce and consume
XML.
However, several XML annotations are provided for handling namespaces and fine-tuning the format of the XML produced.
The following example shows XML for a typical bean:
Sample Beans
Sample Code
Person p =
Normal XML:
Juneau produces JSON-equivalent XML, meaning any valid JSON document can be losslessly converted into an XML
equivalent.
In fact, all of the Juneau serializers and parsers are built upon this JSON-equivalence.
2.16.1 - XML Methodology
The following examples show how different data types are represented in XML. They mirror how the data structures are represented in JSON.
Simple types
The representation of loose (not a direct bean property value) simple types are shown below:
| Data type | JSON example | XML |
|---|---|---|
| string | ||
| boolean | ||
| integer | 123 | |
| float | 1.23 | |
| null |
Maps
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: |
Arrays
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> |
[
|
Beans
| Data type | JSON example | XML |
|---|---|---|
|
|
{
a: |
Beans with Map properties
| Data type | JSON example | XML |
|---|---|---|
|
|
{
a: {
k1: |
2.16.2 - XML Serializers
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:
2.16.3 - XML Parsers
The XmlParser class is used to parse XML into POJOs.
The XML parser provides the following settings:
The following pre-configured parsers are provided for convenience:
2.16.4 - @Bean(typeName) Annotation
The @Bean.typeName() annotation can be used to
override the Juneau default name on bean elements.
Types names serve two distinct purposes:
- To override the element name.
- To serve as a class identifier so that the bean class can be inferred during parsing if it cannot automatically be inferred through reflection.
Example
| Data type | JSON example | Without annotation | With annotation |
|---|---|---|---|
|
|
{
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.
Example
| Java | Without annotation | With annotation |
|---|---|---|
|
|
-
string,number,boolean,object,array, andnullare 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
Examples
| 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
Whitespace characters in element names are encoded as well as whitespace end characters in text.
| 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.
2.16.5 - @Xml(childName) Annotation
The @Xml.childName() annotation can be used to
specify the name of XML child elements for bean properties of type collection or array.
Example
| Data type | JSON example | Without annotation | With annotation |
|---|---|---|---|
|
|
{
a: [ |
||
|
|
{ a: [123,456] } |
2.16.6 - @Xml(format) Annotation
The @Xml.format() annotation can be used to tweak
the XML format of a POJO.
The value is set to an enum value of type XmlFormat.
This annotation can be applied to both classes and bean properties.
The XmlFormat.ATTR format can be applied to bean properties to
serialize them as XML attributes instead of elements.
Note that this only supports properties of simple types (e.g. strings, numbers, booleans).
Example
| Data type | JSON example | Without annotation | With annotation |
|---|---|---|---|
|
|
{
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.
Example
| 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.
Example
| 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.
Example
| Data type | JSON example | Without annotation | With annotation |
|---|---|---|---|
|
|
{
a: {
k1: |
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,
This makes it impossible to differentiate between an empty element and an element containing an empty
string.
This causes empty strings to get lost in translation.
To alleviate this, we use the constructs
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: |
2.16.7- Namespaces
Let's go back to the example of our original Person bean class, but add some namespace annotations:
Sample Beans
The namespace URLs can either be defined as part of the @Xml
annotation, or can be defined at the package level with the @XmlSchema
annotation.
Below shows it defined at the package level:
package-info.java
Sample Code
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.
2.16.8- URI Properties
2.16.9 - XML-Schema Support
Juneau provides the XmlSchemaSerializer class for generating XML-Schema
documents that describe the output generated by the XmlSerializer class.
This class shares the same properties as XmlSerializer.
Since the XML output differs based on settings on the XML serializer class, the XML-Schema serializer
class must have the same property values as the XML serializer class it's describes.
To help facilitate creating an XML Schema serializer with the same properties as the corresponding
XML serializer, the XmlSerializer.getSchemaSerializer() method
has been added.
XML-Schema requires a separate file for each namespace.
Unfortunately, does not mesh well with the Juneau serializer architecture which serializes to single writers.
To get around this limitation, the schema serializer will produce a single output, but with multiple
schema documents separated by the null character (
Lets start with an example where everything is in the same namespace.
We'll use the classes from before, but remove the references to namespaces.
Since we have not defined a default namespace, everything is defined under the default Juneau namespace.
Sample Beans
The code for creating our POJO model and generating XML Schema is shown below:
XML-Schema results
Now if we add in some namespaces, we'll see how multiple namespaces are handled.
Sample Beans with multiple namespaces
The schema consists of 4 documents separated by a
XML-Schema results
For convenience, the #getValidator(SerializerSession,Object) method is provided to create a
Validator using the input from the serialize method.
2.17 - HTML Details
2.17.1 - HTML Methodology
The following examples show how different data types are represented in HTML. They mirror how the data structures are represented in JSON.
Simple types
The representation for simple types mirror those produced by the XML serializer. Tags are added to help differentiate data types when they cannot be inferred through reflection. These tags are ignored by browsers and treated as plain text.
| Data type | JSON example | HTML |
|---|---|---|
| string | ||
| boolean | ||
| integer | 123 | |
| float | 1.23 | |
| null |
Maps
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: |
Arrays
Collections and arrays are represented as ordered lists.
| Data type | JSON example | HTML |
|---|---|---|
| String[] |
[
|
|
| Number[] |
[
123,
1.23,
|
|
| Object[] |
[
|
|
| String[][] |
[
[ |
|
|
|
[ 123 ] | |
|
|
[
|
Collections
| Data type | JSON example | HTML |
|---|---|---|
| List<String> |
[
|
|
| List<Number> |
[
123,
1.23,
|
|
| List<Object> |
[
|
Beans
| Data type | JSON example | HTML |
|---|---|---|
|
|
{
a: |
Beans with Map properties
| Data type | JSON example | HTML |
|---|---|---|
|
|
{
a: {
k1: |
2.17.2 - HTML Serializers
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:
2.17.3 - HTML Parsers
The HtmlParser class is used to parse HTML into POJOs.
They can also parse the contents produced by HtmlDocSerializer.
The HTML parser provides the following settings:
The following pre-configured parsers are provided for convenience:
2.17.4 - @Html Annotation
2.17.5 - @Html(render) Annotation
2.17.6 - HtmlDocSerializer
2.17.7 - Custom Templates
2.17.8 - HTML-Schema Support
2.18 - UON Details
Juneau supports converting arbitrary POJOs to and from UON strings using ultra-efficient serializers
and parsers.
The serializer converts POJOs directly to UON strings without the need for intermediate DOM objects
using a highly-efficient state machine.
Likewise, the parser creates POJOs directly from UON strings without the need for intermediate DOM
objects.
Juneau uses UON (URL-Encoded Object Notation) for representing POJOs. The UON specification can be found here.
The following example shows JSON for a typical bean:
Sample Beans
Sample Code
Person p =
UON
(
2.18.1 - UON Methodology
General methodology:
| 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.
2.18.2 - UON Serializers
The UonSerializer class is used to serialize POJOs into UON.
The UON serializers provides the following settings:
The following pre-configured serializers are provided for convenience:
2.18.3 - UON Parsers
The UonParser class is used to parse UON into POJOs.
The UON parser provides the following settings:
The following pre-configured parsers are provided for convenience:
2.19 - URL-Encoding Details
Juneau supports converting arbitrary POJOs to and from URL-encoded strings using ultra-efficient serializers
and parsers.
The serializer converts POJOs directly to URL-encoded strings without the need for intermediate DOM objects
using a highly-efficient state machine.
Likewise, the parser creates POJOs directly from URL-encoded strings without the need for intermediate DOM
objects.
Juneau uses UON (URL-Encoded Object Notation) for representing POJOs as URL-Encoded values in key-value pairs. The UON specification can be found here.
The following example shows JSON for a typical bean:
Sample Beans
Sample Code
Person p =
URL-Encoding
2.19.1 - URL-Encoding Methodology
General methodology:
| 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.
2.19.2 - URL-Encoding Serializers
The UrlEncodingSerializer class is used to serialize POJOs into URL-Encoding.
The URL-Encoding serializers provides the following settings:
The following pre-configured serializers are provided for convenience:
2.19.3 - URL-Encoding Parsers
The UrlEncodingParser class is used to parse URL-Encoding into POJOs.
The URL-Encoding parser provides the following settings:
The following pre-configured parsers are provided for convenience:
2.19.4 - @UrlEncoding Annotation
2.20 - MessagePack Details
2.20.1 - MessagePack Methodology
2.20.2 - MessagePack Serializers
The MsgPackSerializer class is used to serialize POJOs into MessagePack.
The MessagePack serializer provides the following settings:
The following pre-configured serializers are provided for convenience:
2.20.3 - MessagePack Parsers
The MsgPackParser class is used to parse MessagePack into POJOs.
The MessagePack parser provides the following settings:
The following pre-configured parsers are provided for convenience:
2.21 - SOAP Details
2.22 - CSV Details
2.23 - Java Serialized Object Details
2.24 - Best Practices
-
Reuse instances of serializers and parsers whenever possible.
They are designed to be thread safe and maintain internal caches of bean metadata to increase performance. -
The
SERIALIZER_detectRecursionsoption on theSerializerclass can cause a performance penalty of around 20%.
Therefore, it's recommended that this option be used only when necessary. -
In general, JSON serialization and parsing is about 20% faster than XML.
JSON is also more compact than XML.
MessagePack is fastest and most compact of all. -
The RDF parsers are SLOW.
RDF simply isn't efficient with node traversal, so creating tree structures out of RDF models is highly inefficient. -
The
Parsermethods that take inClassMetaparameters are slightly faster than methods that take inClassorObjectparameters, since the latter methods involve hash lookups to resolve toClassMetaparameters.
3 - juneau-marshall-rdf
Maven Dependency
Java Library
juneau-marshall-rdf-7.2.0.jar
OSGi Module
org.apache.juneau.marshall.rdf_7.2.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:
- RDF/XML
- RDF/XML-Abbrev
- N-Triple
- Turtle
- N3
3.1 - RDF Details
Juneau supports serializing and parsing arbitrary POJOs to and from the following RDF formats:
- RDF/XML
- Abbreviated RDF/XML
- N-Triple
- Turtle
- N3
The serializers and parsers work identically to those in juneau-marshall, but are
packaged separately so that you don't need to pull in the Jena dependency unless you need it.
3.1.1 - RDF Methodology
3.1.2 - RDF Serializers
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:
- Common Properties
- Common Serializer Properties
RdfCommonRDF_arp_embeddingRDF_arp_err_RDF_arp_errorModeRDF_arp_ign_RDF_arp_iriRulesRDF_arp_warn_RDF_collectionFormatRDF_juneauBpNsRDF_juneauNsRDF_languageRDF_looseCollectionsRDF_n3_abbrevBaseUriRDF_n3_indentPropertyRDF_n3_minGapRDF_n3_objectListsRDF_n3_propertyColumnRDF_n3_subjectColumnRDF_n3_useDoublesRDF_n3_usePropertySymbolsRDF_n3_useTripleQuotedStringsRDF_n3_widePropertyLenRDF_rdfxml_allowBadUrisRDF_rdfxml_attributeQuoteCharRDF_rdfxml_blockRulesRDF_rdfxml_longIdRDF_rdfxml_relativeUrisRDF_rdfxml_showDoctypeDeclarationRDF_rdfxml_showXmlDeclarationRDF_rdfxml_tabRDF_rdfxml_xmlBaseRDF_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.
3.1.3 - Rdf Parsers
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:
- Common Properties
- Common Parser Properties
RdfCommonRDF_arp_embeddingRDF_arp_err_RDF_arp_errorModeRDF_arp_ign_RDF_arp_iriRulesRDF_arp_warn_RDF_collectionFormatRDF_juneauBpNsRDF_juneauNsRDF_languageRDF_looseCollectionsRDF_n3_abbrevBaseUriRDF_n3_indentPropertyRDF_n3_minGapRDF_n3_objectListsRDF_n3_propertyColumnRDF_n3_subjectColumnRDF_n3_useDoublesRDF_n3_usePropertySymbolsRDF_n3_useTripleQuotedStringsRDF_n3_widePropertyLenRDF_rdfxml_allowBadUrisRDF_rdfxml_attributeQuoteCharRDF_rdfxml_blockRulesRDF_rdfxml_longIdRDF_rdfxml_relativeUrisRDF_rdfxml_showDoctypeDeclarationRDF_rdfxml_showXmlDeclarationRDF_rdfxml_tabRDF_rdfxml_xmlBaseRDF_useXmlNamespaces
RdfParser
3.1.4 - @Rdf Annotation
3.1.5 - Namespaces
You'll notice in the previous example that Juneau namespaces are used to represent bean property names.
These are used by default when namespaces are not explicitly specified.
The juneau namespace is used for generic names for objects that don't have namespaces
associated with them.
The juneaubp namespace is used on bean properties that don't have namespaces associated with
them.
The easiest way to specify namespaces is through annotations.
In this example, we're going to associate the prefix 'per' to our bean class and all properties
of this class.
We do this by adding the following annotation to our class:
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.
3.1.6 - URI Properties
Bean properties of type java.net.URI or java.net.URL have special meaning to the
RDF serializer.
They are interpreted as resource identifiers.
In the following code, we're adding 2 new properties.
The first property is annotated with
The second un-annotated property is interpreted as a reference to another resource.
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
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.
3.1.7 - Root Property
For all RDF languages, the POJO objects get broken down into simple triplets.
Unfortunately, for tree-structured data like the POJOs shown above, this causes the root node of the tree
to become lost.
There is no easy way to identify that person/1 is the root node in our tree once in triplet
form, and in some cases it's impossible.
By default, the RdfParser class handles this by scanning all the nodes and
identifying the nodes without incoming references.
However, this is inefficient, especially for large models.
And in cases where the root node is referenced by another node in the model by URL, it's not possible to
locate the root at all.
To resolve this issue, the property RdfSerializer.RDF_addRootProperty
was introduced.
When enabled, this adds a special root attribute to the root node to make it easy to locate
by the parser.
To enable, set the
Now when we rerun the sample code, we'll see the added root attribute on the root resource.
3.1.8 - Typed Literals
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.
4 - juneau-dto
Maven Dependency
Java Library
juneau-dto-7.2.0.jar
OSGi Module
org.apache.juneau.dto_7.2.0.jar
The juneau-dto library contains several predefined POJOs for generating commonly-used document types.
This section describes support for these POJOs.
4.1 - HTML5
The Juneau HTML5 DTOs are simply beans with fluent-style setters that allow you to quickly construct HTML fragments as Java objects. These object can then be serialized to HTML using one of the existing HTML serializers, or to other languages such as JSON using the JSON serializers.
The HtmlBuilder class is a utility class with predefined static methods
that allow you to easily construct DTO instances in a minimal amount of code.
The following examples show how to create HTML tables.
| Java code | HTML |
|---|---|
|
|
|
|
|
|
|
|
Using the HTML5 DTOs, you should be able to construct any valid HTML5 from full document bodies to any possible fragments.
The HtmlParser class can be used convert these HTML documents back
into POJOs.
Other serializers and parsers (e.g. JsonSerializer) can be used to
represent these POJOs in languages other than HTML.
Additional Information - org.apache.juneau.dto.html5
4.2 - Atom
The Juneau ATOM feed DTOs are simply beans with fluent-style setters.
The following code shows a feed being created programmatically using the
AtomBuilder class.
To serialize this to ATOM, use the XmlSerializer class:
Example with no namespaces
Results
The XmlParser class can be used convert these Atom documents back into POJOs.
Other serializers and parsers (e.g. JsonSerializer) can be used to
represent these POJOs in languages other than XML.
Additional Information - org.apache.juneau.dto.atom
4.3 - Swagger
The Juneau Swagger DTOs are simply beans with fluent-style setters that allow you to quickly construct
Swagger documents as Java objects.
These object can then be serialized to JSON using one of the existing JSON serializers, or to other
languages such as XML or HTML using the other serializers.
The SwaggerBuilder class is a utility class with predefined static
methods that allow you to easily construct DTO instances in a minimal amount of code.
The following is an example Swagger document from the Swagger website.
{
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.
5 - juneau-svl
Maven Dependency
Java Library
juneau-svl-7.2.0.jar
OSGi Module
org.apache.juneau.svl_7.2.0.jar
5.1 - Simple Variable Language
The
In a nutshell, Simple Variable Language (or SVL) is text that contains variables of the form
It is used extensively in the Config, REST and Microservice APIs.
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}NotEmptyVar-$NE{arg}UpperCaseVar-$UC{arg}LowerCaseVar-$LC{arg}
Example:
The following shows how variables can be arbitrarily nested...
5.2 - SVL Variables
Variables are defined through the Var API.
The API comes with several predefined variables and is easily extensible.
The following is an example of a variable that performs URL-Encoding on strings.
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} | |
NotEmptyVar |
$NE{arg} | |
UpperCaseVar |
$UC{arg} | |
LowerCaseVar |
$LC{arg} | |
| juneau-config | ConfigVar |
$C{key[,default]} |
| juneau-rest-server | FileVar |
$F{path[,default]}} |
ServletInitParamVar |
$I{name[,default]} | |
LocalizationVar |
$L{key[,args...]} | |
RequestAttributeVar |
$RA{key1[,key2...]} | |
RequestFormDataVar |
$RF{key1[,key2...]} | |
RequestHeaderVar |
$RH{key1[,key2...]} | |
RequestHeaderVar |
$RI{key} | |
RequestPathVar |
$RP{key1[,key2...]} | |
RequestQueryVar |
$RQ{key1[,key2...]} | |
RequestVar |
$R{key1[,key2...]} | |
SerializedRequestAttrVar |
$SA{contentType,key[,default]} | |
UrlVar |
$U{uri}> | |
UrlEncodeVar |
$UE{uriPart} | |
WidgetVar |
$W{name} |
5.3 - VarResolvers and VarResolverSessions
The main class for performing variable resolution is VarResolver.
Two methods are provided for resolving variables:
VarResolverresolve(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:
- Context-objects - Objects set on the resolver.
- Session-objects - Objects set on the resolver session.
The following two classes are identical in behavior except for which objects they can access:
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.
Example:
5.4 - Other Notes
-
The escape character
'\' can be used when necessary to escape the following characters:$ , { } -
WARNING: It is possible to cause
StackOverflowErrorsif your nested variables result in a recursive loop (e.g. the environment variable'MYPROPERTY'has the value'$E{MYPROPERTY}'). So don't do that! -
As a general rule, this class tries to be as efficient as possible by not creating new strings when not
needed.
For example, calling the resolve method on a string that doesn't contain variables (e.g.resolver.resolve() will simply be a no-op and return the same string."foobar" )
6 - juneau-config
Maven Dependency
Java Library
juneau-config-7.2.0.jar
OSGi Module
org.apache.juneau.config_7.2.0.jar
6.1 - Overview
The juneau-config library contains a powerful API for creating and using INI-style config files.
Example configuration file:
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:
-
Support for storing and retrieving any of the following data types:
- Primitives
- POJOs
- Beans
- Arrays, Maps, and Collections of anything
- Binary data
- Transactional modifications with commit/rollback capabilities.
- A listener API.
- Filesystem watcher integration allowing changes on the file system to be reflected in real-time.
-
Modifications through the Config class (e.g. add/remove/modify sections and keys, add/remove comments and whitespace, etc...)
DO NOT cause loss of formatting in the file.
All existing whitespace and comments are preserved for you! - Value encoding for added security.
- Support for SVL variables.
- Directly populate beans from config sections.
- Accessing config sections through Java interface proxies.
- An extensible storage API allows you to write your own config storage (e.g. storage in databases or the cloud).
6.1.1 - Syntax Rules
-
Each config file contains zero or more sections containing zero or more entries:
[Section1] key1 =1 [Section2] key1 =2 -
Unicode escapes can be used in values.
key1 =\u0070\u0075\u0062\u006c\u0069\u0063 -
Comment lines start with the
'#' character and can be placed on lines before sections and entries:# A comment about this section [Section1] # A comment about this entry key1 =1 -
Comments can also be placed on the same line as entries:
key1 =1 # A comment about this entry -
Values containing
'#' must be escaped to prevent identification as a comment character:valueContainingPound =Value containing \u0023 character
Likewise,'\' should be escaped to prevent confusion with unicode escapes. -
Values containing newlines can span multiple lines.
Subsequent lines start with a tab character.multiLineValue =line 1, line 2, line 3
When retrieved, the above translates to"line1,\nline2,\nline3" . - Leading and trailing whitespace on values are ignored.
- Whitespace is not ignored within multi-line values (except for the leading tab character on each line).
-
Blank lines can be used anywhere in the file.
# A comment line # Another comment line [Section1] ... -
Values located before any sections are considered part of the no-name section, meaning
they are accessed simply by key and not section/key.
# Top of file # Use config.getString("key1") to retrieve. key1 =val1 # The first section [Section1] # Use config.getString("Section1/key2") to retrieve. key2 =val2 -
Section and key names must be at least one character long and not consist of any of the following
characters:
/ \ [ ] = #
- Whitespace in section and key names is technically allowed but discouraged.
6.2 - Entry Types
Configuration files can contain entries for anything from primitive types up to complex hierarchies of POJOs consisting of maps, collections, and/or beans.
6.2.1 - Primitive Types
The most common case for configuration values are primitives.
The following methods are provided for accessing primitive values:
On integers and longs,
Numbers can also use hexadecimal and octal notation:
Strings with newlines get broken into separate lines:
Typically, multi-line values are started on the next line for clarity like so:
6.2.2 - POJOs
The following methods are provided for accessing POJO values:
In theory, any parsable POJO type can be represented
as a config value.
However in practice, we're typically talking about the following:
- Objects convertible from Strings.
- Beans.
An example of an object convertible from a String was already shown in an example above.
In that case, it was a URL which has a public constructor that takes in a String:
Beans are represented as Lax 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:
6.2.3 - Arrays
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(
6.2.4 - Collections
The following methods are provided for accessing maps and collections:
The Type,Type... arguments allow you to specify the component types for maps and collections.
List class arguments can be followed by zero or one arguments representing the entry types.
Map class arguments can be followed by zero or two arguments representing the key and value types.
The arguments can be chained to produce any data structure consisting of maps, collections, or POJOs.
Examples are shown below:
getObject("..." , List.class )
Produces:List<?>getObject("..." , LinkedList.class )
Produces:LinkedList<?>getObject("..." , HashSet.class , Integer.class )
Produces:HashSet<Integer>getObject("..." , Map.class )
Produces:Map<?,?>getObject("..." , HashMap.class )
Produces:HashMap<?,?>getObject("..." , LinkedHashMap.class , String.class , MyBean.class )
Produces:LinkedHashMap<String,MyBean>getObject("..." , HashMap.class , Integer.class , ArrayList.class , MyBean[].class )
Produces:LinkedHashMap<Integer,ArrayList<MyBean[]>>
Example:
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(
6.2.5 - Binary Data
The following methods are provided for accessing binary data:
Binary data can be represented in 3 formats:
- BASE-64 (default)
Example:"Zm9vYmFycw==" - Hexadecimal
Example:"666F6F62617273" - Spaced hexadecimal
Example:"66 6F 6F 62 61 72 73"
The binary data format is controlled via the following setting:
For example:
Binary lines can be split up into separate lines for readability:
Binary data line wrapping can be controlled via the following setting:
6.3 - Variables
Config files can contain variables that get resolved dynamically using the previously-described VarResolver API.
Example:
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:
6.3.1 - Logic Variables
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:
6.4 - Encoded Entries
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().
6.5 - Section Maps
Config sections can be retrieved in-bulk using
Config.getSectionAsMap(String).
Example:
Maps created this way are snapshot copies of the section at the time of the method call.
6.6 - Section Beans
Config files can also be used to directly populate beans using
Config.getSectionAsBean(String,Class,boolean).
Example:
Like maps, beans created this way are snapshot copies of the section at the time of the method call.
6.7 - Section Interfaces
Config sections can also be accessed via interface proxies using
Config.getSectionAsInterface(String,Class).
While section maps and beans retrieve copies of the configuration data at the time of the method call, section interfaces can also be use to set values in the underlying configuration.
Example:
6.8 - Setting Values
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
To unset the same-line comment, you should pass in a blank string.
To remove pre-lines, you should pass in an empty list.
Sections can be added with optional pre-lines using the setSection methods:
Changes made to the configuration are transactional in nature.
They are kept in memory until you call the Config.commit() method.
Until then, you still see the modified values when you call any of the getters, but the modified values
exist only in memory.
Changes can be rolled back using the Config.rollback() method.
6.8.1 - File System Changes
In general, external file modifications will be detected immediately in the Config
object when a watcher thread is enabled (explained later).
Otherwise, they are detected when a commit is performed.
The Config object maintains an in-memory record of all changes that have been applied to it
through getters and setters.
When the underlying file changes, the new contents are loaded and the in-memory changes are then
applied to the new configuration.
This provides the benefits of real-time updates of configurations while not losing any changes made in the JVM.
If the commit() method is called on the Config objects after the file system
contents have been modified, we will then reload the configuration from the file system, apply the
changes, and then try to save to the file system again (up to 10 times).
If the same entry is both internally and externally modified, the external modification will be overwritten (although both change events will be seen by listeners).
6.8.2 - Custom Entry Serialization
Setter methods that take in a Serializer can be used to provide custom serialization of entries
instead of using the predefined serializer.
The value can then be retrieved using the equivalent parser:
Address myAddress = c.getObject(
6.8.3 - Setting Values in Bulk
The following methods can be used to bulk-load configuration values:
Changes can then be committed using the Config.commit() method.
6.9 - Listeners
Configuration change events can be listened for using the following methods:
The ConfigEventListener interface consists of the following method:
The ConfigEvent class provides access to all the information about the updated entry:
The listener method is triggered:
- After
Config.commit()is called. - When the file changes on the file system.
In both cases, the listener is triggered after the changes have been committed.
6.10 - Serializing
The following methods are used for serializing Config objects back into INI files:
Both methods are thread safe.
The Config class implements the Writable which means it can be
returned as-is by REST methods to be serialized as INI text.
6.11 - Config Stores
Configuration files are stored in entities called Stores.
The methods that need to be implemented on a store are:
ConfigStoreread(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:
Example:
The default store used is ConfigFileStore.DEFAULT which defines
the execution directory as the file system directory to store and retrieve files.
6.11.1 - ConfigMemoryStore
The ConfigMemoryStore class is simply an in-memory storage
location for configuration files.
There is no hard persistence and is used primarily for testing purposes.
However, the implementation provides a good idea on how stores work (especially the write method):
6.11.2 - ConfigFileStore
The ConfigFileStore is the typical store used for configuration files.
It provides the following configurable settings:
Example:
6.11.3 - Custom ConfigStores
The ConfigStore API has been written to allow easy development of custom configuration storage classes.
The example below shows a starting point for an implementation based on polling a relational database.
Completing it is left as an exercise:
Example Store Class:
The purpose of the builder class is to simply set values in the PropertyStore
that's passed to the ConfigStore:
Example Builder Class:
6.11.4 - ConfigStore Listeners
The ConfigStore class has the following listener methods:
ConfigStoreregister(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:
ConfigStoreListenerConfigStoreListener.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.
6.12 - Read-only Configs
The following settings can be used to create read-only Config objects:
Example:
This causes all methods that make modifications to throw UnsupportedOperationException.
6.13 - Closing Configs
In general, it's good practice to close Config if you're only creating them temporarily so that their listeners get unregistered from the underlying storage APIs.
Example:
7 - juneau-rest-server
Maven Dependency
Java Library
juneau-rest-server-7.2.0.jar
OSGi Module
org.apache.juneau.rest.server_7.2.0.jar
The
The primary goal for Juneau was to make it as easy as possible to implement easy-to-read and self-documenting
REST resources using very little code.
One of the biggest advantages of the Juneau REST framework over similar architectures is that it hides the
serialization layer from the developer.
The developer can work entirely with POJOs and let the Juneau framework handle all the serialization and
parsing work.
The developer need never know what the
The API builds upon the existing JEE Servlet API.
The root class, RestServlet is nothing but a specialized
HttpServlet, and the RestRequest and
RestResponse classes are nothing more than specialized
HttpServletRequest and HttpServletResponse objects.
This allows maximum flexibility for the developer since you can let Juneau handle operations such as
serialization, or you can revert to the existing servlet APIs to do low-level processing of requests yourself.
It also means you need nothing more than a Servlet container such as Jetty to use the REST framework.
Features
-
Serializes POJOs to JSON, XML, HTML, URL-Encoding, UON, RDF/XML, N-Triple, Turtle, N3, SOAP, or
Java-serialized-object based on value of
Accept header.
No user code is required to handle these types.- Extensible design that provides ability to override existing content type handlers, or add the ability to handle other kinds of content types.
- Parses content of POST/PUT request bodies to POJOs.
-
Automatic built-in ability to serialize POJO metadata to JSON+SCHEMA, XML+SCHEMA, or HTML+SCHEMA based on
Accept header. -
Automatic negotiation of output Writer based on HTTP headers.
- Automatic handling of
Accept-Charset header for all character sets supported by the JVM. - Automatic handling of
Accept-Encoding header with registered encoders.
- Automatic handling of
-
Automatic error handling.
- Automatic 401 errors (Unauthorized) on failed guards.
- Automatic 404 errors (Not Found) on unmatched path patterns.
- Automatic 405 errors (Method Not Implemented) on unimplemented methods.
- Automatic 406 errors (Not Acceptable) when no matching serializer was found to handle the
Accept header. - Automatic 412 errors (Precondition Failed) when all matchers failed to match.
- Automatic 415 errors (Unsupported Media Type) when no matching parser was found was found to handle
the
Content-Type header. - Automatic 500 errors on uncaught exceptions.
- Self-documenting Swagger-based REST interfaces.
-
Various useful debugging features that make debugging using a browser extremely simple...
- Ability to pass HTTP header values as URL GET parameters (e.g.
&Accept=text/xml ). - Ability to pass HTTP content on PUT/POST requests as a URL GET parameter
(e.g.
&content={foo:"bar"} ). - Ability to simulate non-GET requests using a
&method GET parameter (e.g.&method=POST ). - Ability to force
"text/plain" on response using GET parameter&plainText=true .
- Ability to pass HTTP header values as URL GET parameters (e.g.
-
Ability to implement overloaded HTTP methods through the use of the
&method attribute (e.g.&method=FOO ). -
Ability to match URL patterns (e.g.
/foo/{fooId}/bar/{barId} ) against URLs (e.g./foo/123/bar/456/bing ). -
Ability to associate guards at the resource or method levels through annotations.
Typically useful for security, but can be used for a variety of purposes. -
Ability to associate converters at the resource or method levels through annotations.
Typically useful for performing conversions on input and output, such as for supporting older input and output formats.
Many of the examples in this document are pulled directly from
7.1 - Hello World Example
A REST resource is simply a Java class annotated with RestResource.
The most common case is a class that extends RestServlet, which itself is simply an
extension of HttpServlet which allows it to be deployed as a servlet.
In this example, we define a resource called
This example is located in the
It's assumed the reader is familiar with defining servlets in web applications.
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.
7.2 - Class Hierarchy
The class hierarchy for the REST servlet class is shown below:
-
javax.servlet.http.HttpServlet-
org.apache.juneau.rest.RestServlet
Contains all the main logic.org.apache.juneau.rest.BasicRestServlet
Provides a default set of serializers, parsers, options page, stylesheet, and other common settings.org.apache.juneau.rest.BasicRestServletGroup
A default implementation for "router" pages.
-
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.
7.3 - Instantiation
REST resources are deployed in one of two ways:
- Deployed in a J2EE container as a servlet.
- Deployed as a child of another REST resource.
When deployed in a J2EE container, you MUST extend from one of the servlet classes.
When deployed as a child of another resource, you MAY extend from one of the servlet classes but it's
not necessary.
The only requirement is that the class be annotated with
public T()public T(RestContextBuilder)
And even that restriction is relaxed if you implement your own REST resource resolver (described later).
7.3.1 - RestServlet
The RestServlet class is the entry point for your REST resources.
It extends directly from
When the servlet
These get constructed into a RestContext object that holds all the configuration
information about your resource in a read-only object.
Most developers are not going to be using the BasicRestServlet.
The
However, the class does provide a couple of convenience methods to be aware of:
RestServletextends HttpServlet
Since this is a servlet, you also have the ability to intercept calls to the
7.3.2 - BasicRestServlet
The BasicRestServlet class is a subclass of RestServlet
preconfigured with the following:
- A default set of serializers and parsers (pretty much all of them except for the RDF ones).
- Some basic HTML boilerplate for the HTML representation of your POJOs.
- Support for auto-generated Swagger documentation through OPTIONS page requests.
- Configuration of default CSS stylesheets.
The entirety of the class is shown below.
You should notice that very little code is being used and everything is configurable through
annotations:
Your top-level resource will simply extend from this class, as shown in the Hello World example from a couple sections back.
There's a lot going on in this class.
But not to worry, the details will be described later.
7.3.3 - Children
Child Resources are REST servlets or objects that are linked to parent resources through the
@RestResource.children() annotation.
Example:
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
Initialization of and access to the child resources occurs through the parent resource.
Children can be nested arbitrary deep to create complex REST interfaces with a single top-level REST servlet.
See Also:
7.3.4 - Router Pages
The BasicRestServletGroup class provides a default "router" page for
child resources when a parent resource is nothing more than a grouping of child resources.
The
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
The method returns a POJO with is just a linked-list of beans with name/description properties.
7.3.5 - Resource Resolvers
By default, you can add the @RestResource
to any class as long as it has one of the following constructors:
public T()public T(RestContextBuilder)
The latter constructor can be used to get access to the RestContextBuilder object to make
any configurations to the resource before it's initialized.
Resource object resolution is controlled through the following API:
This API can be extended to provide your own custom resource resolution.
Later topics discuss how to use this API to instantiate resources using Spring.
See Also:
7.3.6 - Lifecycle Hooks
Lifecycle hooks allow you to hook into lifecycle events of the servlet/resource creation and REST calls.
For example, if you want to add an initialization method to your resource:
Or if you want to intercept REST calls:
The hook events can be broken down into two categories:
- Resource lifecycle events:
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.
- REST call lifecycle events:
START_CALL- At the beginning of a REST call.PRE_CALL- Right before the@RestMethod method is invoked.POST_CALL- Right after the@RestMethod method is invoked.END_CALL- At the end of the REST call after the response has been flushed.
See Also:
7.4 - @RestResource
The @RestResource annotation is the primary way of defining
and configuring REST resource classes.
The functionality of the class itself is covered in detail in the topics below.
7.4.1 - Annotation Inheritance
The @RestResource annotation can also be used on parents and interfaces of resource classes.
When multiple annotations are defined at different levels, the annotation values are combined.
This is a particularly useful feature because it allows you to define your own configured parent resource classes that can be extended by all your child resources so that they all share common settings.
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 are combined with those on parent class. |
pojoSwaps() |
POJO swaps on child are combined with those on parent class. |
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 are combined with those on parent class.
Serializers on methods take precedence over those on classes. |
parsers() |
Parsers on child are combined with those on parent class.
Parsers on methods take precedence over those on classes. |
responseHandlers() |
Response handlers on child are combined with those on parent class. |
encoders() |
Encoders on child are combined with those on parent class. |
defaultRequestHeaders() |
Headers on child are combined with those on parent class.
Headers are applied parent-to-child in the order they appear in the annotation. Headers on methods take precedence over those on classes. |
defaultResponseHeaders() |
Headers on child are combined with those on parent class.
Headers are applied parent-to-child in the order they appear in the annotation. |
children() |
Children on child are combined with those on parent class.
Children are list parent-to-child in the order they appear in the annotation. |
path() |
Path is searched for in child-to-parent order. |
title() |
Label is searched for in child-to-parent order. |
description() |
Description is searched for in child-to-parent order. |
config() |
Config file is searched for in child-to-parent order. |
staticFiles() |
Static files on child are combined with those on parent class.
Static files are are executed child-to-parent in the order they appear in the annotation. |
7.5 - RestContext
The RestContext object is the workhorse class for all of the configuration
of a single REST resource class.
It's by-far the most important class in the REST API.
Every class annotated with
The object itself is read-only and unchangeable.
It is populated through the following:
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: This class is huge.
Through it, you can configure bean/serializer/parser settings, define config files, children,
resource finders, info providers, etc...
7.6 - @RestMethod
REST Java methods are identified on REST servlets using the
@RestMethod annotation.
The annotation allows the framework to identify the available REST methods through reflection.
Example:
There are no restrictions on the name of the Java method.
7.6.1 - Java Method Parameters
Java methods can contain any of the following parameters in any order:
-
Parameters based on class types:
- Request/response objects:
RestRequest- The request object.HttpServletRequest- The superclass ofRestRequest.RestResponse- The response object.HttpServletResponse- The superclass ofRestResponse.
- Parsed request header values:
- Direct streams on request/response:
InputStreamServletInputStreamReaderOutputStreamServletOutputStreamWriter
- Localization:
ResourceBundle- Client-localized resource bundle.MessageBundle- A resource bundle with additional features.Locale- Client locale.
- Request APIs:
RequestHeaders- API for accessing request headers.RequestQuery- API for accessing request query parameters.RequestFormData- API for accessing request form data.RequestPathMatch- API for accessing path variables.RequestBody- API for accessing request body.
- Other:
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.Swagger- The auto-generated Swagger doc.Config- The external config for the resource.RequestProperties- API for modifying request-time configuration properties.
- Request/response objects:
- Annotated parameters:
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.Method- The HTTP method name.PathRemainder- The remainder value after path pattern match.Body- The HTTP content parsed as a POJO.
Example:
Notes:
- All annotations have programmatic equivalents on the
RestRequestclass.
See Also:
RestContext.REST_paramResolvers- For configuring custom parameter types.
7.6.2 - RestRequest
The RestRequest object is an extension of the
It can be accessed by passing it as a parameter on your REST Java method:
There are many useful methods on this object, but the main ones are shown below:
7.6.3 - RestResponse
The RestResponse object is an extension of the
It can be accessed by passing it as a parameter on your REST Java method:
The important methods on this class are shown below:
RestResponseextends HttpServletResponse
7.6.4 - RequestBody
The RequestBody object is the API for accessing the body of an HTTP request.
It can be accessed by passing it as a parameter on your REST Java method:
Example:
The important methods on this class are:
7.6.5 - RequestHeaders
The RequestHeaders object is the API for accessing the headers of an HTTP request.
It can be accessed by passing it as a parameter on your REST Java method:
Example:
The important methods on this class are:
RequestHeadersextends TreeMap<String,String[]>
7.6.6 - RequestQuery
The RequestQuery object is the API for accessing the GET query parameters of an HTTP request.
It can be accessed by passing it as a parameter on your REST Java method:
Example:
An important distinction between the behavior of this object and
This can be useful in cases where you're mixing GET parameters and FORM POSTS and you don't want to
inadvertantly read the body of the request to get a query parameter.
The important methods on this class are:
RequestQueryextends LinkedHashMap<String,String[]>
7.6.7 - RequestFormData
The RequestFormData object is the API for accessing the HTTP request body as form data.
It can be accessed by passing it as a parameter on your REST Java method:
Example:
Note that this object does NOT take GET parameters into account and only returns values found in the body of the request.
The important methods on this class are:
RequestFormDataextends LinkedHashMap<String,String[]>
7.6.8 - @RestMethod.path()
The @RestMethod.path() annotation allows
you to define URL path patterns to match against.
These patterns can contain variables of the form
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
Any remainder after the match can be accessed through
RequestPathMatch.getRemainder() or parameters with the
@PathRemainder 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
See Also:
7.6.9 - RequestPathMatch
The RequestPathMatch object is the API for accessing the matched variables
and remainder on the URL path.
Example:
The important methods on this class are:
RequestPathMatchextends TreeMap<String,String>
7.6.10 - Method Return Types
The return type can be any serializable POJO as defined in POJO Categories.
It can also be RestResponse.setOutput(Object) method.
Example:
Out-of-the-box, besides POJOs, the following return types are handled as special cases:
InputStream
The contents are simply piped to the output stream returned byRestResponse.getNegotiatedOutputStream().
Note that you should callServletResponseWrapper.setContentType(String)to set theContent-Type header if you use this object type.Reader
The contents are simply piped to the output stream returned byRestResponse.getNegotiatedWriter().
Note that you should callServletResponseWrapper.setContentType(String)to set theContent-Type header if you use this object type.Redirect
Represents an HTTP redirect response.Streamable
Interface that identifies that an object can be serialized directly to an output stream.Writable
Interface that identifies that an object can be serialized directly to a writer.ZipFileList
Special interface for sending zip files as responses.
This is controlled through the following extensible API:
REST Java methods can generate output in any of the following ways:
-
By returning a serializable POJO, or any of the following:
Reader,InputStream,Streamable,Writable -
By calling
RestResponse.setOutput(Object)with any of the types above. -
By accessing the
Writerdirectly by callingRestResponse.getNegotiatedWriter()and writing the output yourself.
Example:
See Also:
RestContext.REST_responseHandlers- For configuring custom response handlers.
7.6.11 - ReaderResource
The ReaderResource class is a convenience object for defining thread-safe
reusable character-based responses.
In essence, it's a container for character data with optional response headers and support for
resolving SVL variables.
The ReaderResource class implements the Writable
interface which is handled by the WritableHandler class.
This allows these objects to be returned as responses by REST methods.
Example:
The important methods on this class are:
7.6.12 - StreamResource
The StreamResource class is the binary equivalent to the ReaderResource object.
In essence, it's a container for binary data with optional response headers.
The StreamResource class implements the Streamable
interface which is handled by the StreamableHandler class.
This allows these objects to be returned as responses by REST methods.
Example:
The important methods on this class are:
7.6.13 - Redirect
The Redirect object is a convenience shortcut for performing HTTP 302 redirects.
RedirectHandler class.
This allows these objects to be returned as responses by REST methods.
The following example shows the difference between handling redirects via
Example:
The constructor can use a
Example:
The arguments are automatically URL-encoded.
Redirecting to the servlet root can be accomplished by simply using the no-arg constructor.
Example:
7.6.14 - @RestMethod.matchers()
RestMatchers are used to allow multiple Java methods to be
tied to the same HTTP method and path, but differentiated by some request attribute such as a specific
header value.
Example:
The interface for matchers is simple:
Notes:
-
If no methods are found with a matching matcher, a
412 Precondition Failed status is returned. - If multiple matchers are specified on the same method, ONLY ONE matcher needs to match for the method to be invoked.
-
Note that you CANNOT define identical paths on different methods UNLESS you use matchers.
That includes paths that are only different in variable names (e.g."/foo/{bar}" and"/foo/{baz}" ).
If you try to do so, aServletException will be thrown on startup. -
Methods with matchers take precedence over methods without.
Otherwise, methods are attempted in the order they appear in the class.
See Also:
7.7 - @Body
The @Body annotation provides easy access to the HTTP body content as any parsable POJO type
In the example below, we're POSTing beans.
The HTTP body of a request can be retrieved as a parsed POJO using either the
RestRequest.getBody() method, or a parameter annotated with
@Body.
The Juneau framework will automatically determine the appropriate
So the body content could be JSON or XML or any other supported parsing types.
See Also:
7.7.1 - Handling Form Posts
The best way to handle a form post is by using an input bean.
The samples include a
The code is shown here:
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.
-
If you're using form input beans, DO NOT use the
@FormData attribute orServletRequestWrapper.getParameter(String)method since this will cause the underlying JEE servlet to parse the HTTP body as a form post.
Your input bean will end up being null since there won't be any content left after the servlet has parsed the body of the request.
This applies to WHENEVER you use@Body orRestRequest.getBody()
7.7.2 - Handling Multi-Part Form Posts
The Juneau framework does not natively support multipart form posts.
However, it can be done in conjunction with the Apache Commons File Upload library.
The samples include a
Example:
7.8 - @FormData
The @FormData annotation is used to retrieve request form post entries.
Example:
This is functionally equivalent to the following code:
The registered RestContext.REST_partParser is used to convert strings
to POJOs and controls what POJO types are supported.
As a general rule, any POJO convertible from a String is supported.
-
This annotation should not be combined with the
@Bodyannotation orRestRequest.getBody()method forapplication/x-www-form-urlencoded POSTposts, since it will trigger the underlying servlet API to parse the body content as key-value pairs resulting in empty content.
The@Queryannotation can be used to retrieve a URL parameter in the URL string without triggering the servlet to drain the body content.
See Also:
7.9 - @Query
The @Query annotation is used to retrieve request URL query parameters.
It's identical to @FormData, but only retrieves the parameter from the URL string, not URL-encoded form posts.
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.
Example:
This is functionally equivalent to the following code:
The registered RestContext.REST_partParser is used to convert strings
to POJOs and controls what POJO types are supported.
As a general rule, any POJO convertible from a String is supported.
See Also:
7.10 - @Header
The @Header annotation is used to retrieve request headers.
Example:
This is functionally equivalent to the following code:
The registered RestContext.REST_partParser is used to convert strings
to POJOs and controls what POJO types are supported.
As a general rule, any POJO convertible from a String is supported.
See Also:
7.11 - Serializers
REST resources use the Serializer API for defining serializers for
serializing response POJOs.
The servlet will pick which serializer to use by matching the request Serializer.getMediaTypes() 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:
See Also:
7.12 - Parsers
REST resources use the Parser API for defining parsers for parsing request
body content and converting them into POJOs.
The servlet will pick which parser to use by matching the request 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:
See Also:
7.13 - Properties
As shown in previous sections, Juneau serializers and parsers are highly-configurable through properties. (See Configurable Properties)
These properties can be defined for serializers and parsers registered on a REST resource via the following:
RestResource.properties()RestContextBuilder- Various methods on the context builder.
Example:
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-overridable: .
Properties are open-ended and can be used for other purposes.
They're made available through the following methods:
See Also:
RestResource.flags()- Shorthand for boolean properties.RestMethod.flags()- Shorthand for boolean properties.RestContextPropertiesRestMethodPropertiesRequestProperties
7.14 - Transforms
The Juneau serializers and parsers can be configured on how to handle POJOs through the use of Transforms. (See Transforms)
Transforms are associated serializers and parsers registered on a REST resource via the following:
RestResource.beanFilters()RestResource.pojoSwaps()RestMethod.beanFilters()RestMethod.pojoSwaps()RestContextBuilder.beanFilters(Object...)RestContextBuilder.pojoSwaps(Object...)
The programmatic equivalent to this is:
7.15 - Guards
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
However, this can be configured by overriding the
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.
See Also:
7.16 - Converters
Converters can be thought of as "post-processors" for POJOs before they get passed to the serializers.
Converters are associated with resource classes and methods via the following:
Example:
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
Provides query parameters that can be used to transform the response (i.e. search/view/sort the POJO response before being serialized). -
Traversable
Allows nodes in the POJO response tree to be individually accessed through additional path info on the request. -
Introspectable
Allows method calls to be made on the response POJO, and for the result of that method call to be serialized as the response.
-
See Also:
7.17 - Messages
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:
See Also:
7.18 - Encoders
The @RestResource.encoders() annotation can
be used to associate character encoders with a servlet class.
Encoders can be used to enable various kinds of compression (e.g.
Example:
Juneau defines the following encoders out-of-the-box:
See Also:
7.19 - SVL Variables
In the previous examples, there were several cases where embedded variables were contained within annotation values:
Variables take the form
This is called Simple Variable Language, or SVL, and is defined here: juneau-svl.
Features
-
Variables can be nested arbitrarily deep (e.g.
"$X{$Y{foo}}" ). -
Variables can contain arguments (e.g.
"$L{my.label,arg1,arg2}" ). -
Variables are recursively resolved.
i.e., if a variable results to a value with another variable in it, that variable will also be resolved (restricted for security reasons on some variables).
Variables are configured on resources via the following API:
Example:
The methods involved with variables are:
RestContext.getVarResolver()RestRequest.getVarResolverSession()RestRequest.getClasspathReaderResource(String,boolean)
There are two distinct groups of variables:
Initialization-time variables
These are variables that can be used in many of the annotations in@RestResource.
TheRestContext.getVarResolver()method returns initialization-time variables only.Request-time variables
These are variables that are available during HTTP-requests and can be used on annotation such as@HtmlDoc.RestRequest.getVarResolverSession()method returns initialization and request-time variables.
The following is the default list of supported variables.
Default REST SVL Variables:
| Module | Class | Pattern | Initialization time | Request time |
|---|---|---|---|---|
| juneau-svl | EnvVariablesVar |
$E{key[,default]} | yes | yes |
SystemPropertiesVar |
$S{key[,default]} | yes | yes | |
ArgsVar |
$A{key[,default]} | yes | yes | |
ManifestFileVar |
$MF{key[,default]} | yes | yes | |
IfVar |
$IF{arg,then[,else]} | yes | yes | |
SwitchVar |
$SW{arg,pattern1:then1[,pattern2:then2...]} | yes | yes | |
CoalesceVar |
$CO{arg1[,arg2...]} | yes | yes | |
PatternMatchVar |
$PM{arg,pattern} | yes | yes | |
NotEmptyVar |
$NE{arg} | yes | yes | |
UpperCaseVar |
$UC{arg} | yes | yes | |
LowerCaseVar |
$LC{arg} | yes | yes | |
| juneau-config | ConfigVar |
$C{key[,default]} | yes | yes |
| juneau-rest-server | FileVar |
$F{path[,default]}} | no | yes |
ServletInitParamVar |
$I{name[,default]} | yes | yes | |
LocalizationVar |
$L{key[,args...]} | no | yes | |
RequestAttributeVar |
$RA{key1[,key2...]} | no | yes | |
RequestFormDataVar |
$RF{key1[,key2...]} | no | yes | |
RequestHeaderVar |
$RH{key1[,key2...]} | no | yes | |
RequestHeaderVar |
$RI{key} | no | yes | |
RequestPathVar |
$RP{key1[,key2...]} | no | yes | |
RequestQueryVar |
$RQ{key1[,key2...]} | no | yes | |
RequestVar |
$R{key1[,key2...]} | no | yes | |
SerializedRequestAttrVar |
$SA{contentType,key[,default]} | no | yes | |
UrlVar |
$U{uri}> | no | yes | |
UrlEncodeVar |
$UE{uriPart} | yes | yes | |
WidgetVar |
$W{name} | no | yes |
7.20 - Configuration Files
The Server API provides methods for associating configuration files with REST servlets so that configuration properties can be defined in external files.
In recap, the Configuration API provides support for INI-style configuration files with embedded string variables:
Example:
These properties are then accessible through the Config class.
Config c = Config.
Configuration files are associated with REST resources through the following:
Example:
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:
See Also:
7.21 - Static files
The @RestResource.staticFiles()
annotation is used to define paths and locations of statically-served files such as images or HTML
documents.
The value is a JSON map of paths to packages/directories located on either the classpath or working directory.
Example:
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
com.foo.mypackage.docs package.[working-dir]/docs directory.
Notes:
-
Mappings are cumulative from parent to child.
Child resources can override mappings made on parent resources. -
The media type on the response is determined by the
RestContext.getMediaTypeForName(String)method.
See Also:
7.22 - Client Versioning
Client version headers are used to support backwards compatibility for breaking REST interface changes.
Using them, you're able to return different responses based on which client is making a request.
The APIs involved with defining client version headers are:
RestResource.clientVersionHeader()RestContextBuilder.clientVersionHeader(String)RestMethod.clientVersion()
Example:
See Also:
7.23 - OPTIONS pages
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).
OPTIONS page for HelloWorld sample resource
http://localhost:10000/helloWorld/?method=OPTIONS
The BasicRestServlet class implements the page by creating a method
mapped to the
This page is constructed using the Info Provider API described next.
7.23.1 - RestInfoProvider
The RestInfoProvider class is used to find the title
and description for your resource and also generate the Swagger documentation.
It can be overridden to provide your own custom Swagger documentation.
The methods on this interface are:
The info provider in turn supplies the information returned by the following methods:
Info providers are registered through the following property:
While you can implement this interface from scratch, you may want to instead consider extending
from the
7.23.2 - BasicRestInfoProvider
The BasicRestInfoProvider class is the default implementation of the
RestInfoProvider interface.
It finds and collects information gathered from the following locations:
- Localized JSON Swagger files in the classpath.
- Reflection.
- annotations.
- Info provided in properties files.
The class itself is designed to be extended if you wish to rely mostly on the default behavior, but tweak certain aspects.
The default provider provides several options for defining Swagger documentation on your resource:
-
Provide nothing.
You'll still get an auto-generated Swagger doc with information gather solely through reflection, including methods, parameters, consumes/produces, etc... -
Specify localized JSON Swagger files on your classpath.
Example:
MyResource_ja_JP.json
-
Use
@RestResource(swagger)and@RestMethod(swagger)annotations on your resource classes and methods.Example:
@RestMethod ( swagger="{tags:'foo,bar,baz'} )public Object myMethod() {...} -
Use properties files identified by the
@RestResource.messages()annotation.Example:
MyResource.myMethod.tags =foo,bar,baz - Use any combination of the above.
-
Extend the
BasicRestInfoProvider and provide customized behavior.Example:
// Our customized info provider. // Extend from the default implementation and selectively override values. public class MyRestInfoProviderextends BasicRestInfoProvider {// Must provide this constructor! public MyRestInfoProvider(RestContext context) {super (context); }@Override /* RestInfoProvider */ public Swagger getSwagger(RestRequest req)throws RestException { Swagger s =super .getSwagger(req);// Made inline modifications to generated swagger. return s; } }// Registered via annotation @RestResource (infoProvider=MyRestInfoProvider.class )public class MyResource {...}
7.24 - @HtmlDoc
The @HtmlDoc annotation is used to customize the HTML
view of your serialized POJOs.
It's used in the following locations:
The annotation itself is just a convenience for setting configuration properties set
on the HtmlDocSerializer class.
For example, the following two pieces of code are equivalent:
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:
See Also:
7.24.1 - Widgets
The Widget class allows you to add arbitrary HTML, CSS, and Javascript
to HTML pages.
They are registered in the following locations:
@HtmlDoc.widgetsRestContextBuilder.widgets(Class...)RestContextBuilder.widgets(Widget...)RestContext.REST_widgets
Example:
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
Example:
See Also:
7.24.2 - Predefined Widgets
7.24.3 - UI Customization
The HTML views of POJOs can somewhat be considered a rudimentary User Interface.
In reality, a better term for them would be a Developer Interface as they're meant to be used
primarily by developers and not end users.
Despite that distinction, it is possible to 'brand' the HTML page to whatever you desire.
The sample root page below includes some default branding for Juneau and Apache:
http://localhost:10000/helloWorld
In particular, you may want to replace these icons:
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.
The Juneau icon shown is a result of the header annotation on the BasicRestServlet class:
The org.apache.juneau.rest.htdocs package and
is served up via the staticFiles annotation (i.e. anything in the org.apache.juneau.rest.htdocs
package is served up under the path /servlet-path/htdocs).
Then we just reference using a URI resolution variable
To change this image, you can extend the
The footer icon shown is generated by a predefined widget:
The widget definition is shown below:
To provide your own footer icon, simply define it in your own footer section:
Note how the "User Interface" is open-ended to pretty much lets you do whatever you want.
7.24.4 - Stylesheets
The sample root page renders in the default "devops" look-and-feel:
http://localhost:10000
The sample root page provides a dropdown widget to try out the other default look-and-feels:
For example, the "light" look-and-feel:
http://localhost:10000/?stylesheet=styles%2Flight.css
And the "dark" look-and-feel:
http://localhost:10000/?stylesheet=styles%2Fdark.css
The stylesheet URL is controlled by the @HtmlDoc.stylesheet() annotation.
The BasicRestServlet class defines the stylesheet served up as a static file:
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
7.25 - Default Headers
The following annotations are provided for specifying default header values for requests and responses:
-
@RestResource.defaultRequestHeaders()
Defines default headers on request when the client doesn't specify them. -
@RestResource.defaultResponseHeaders()
Appends the specified headers if they weren't already set programmatically.
Example:
Default headers can also be specified programmatically by overriding the following methods:
7.26 - Logging and Error Handling
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)
Gets called when an error occurs on a request call.
Default implementation logs the error.
-
The logObjects() method is particularly useful because it allows you to pass in POJOs as arguments
that serialized using JsonSerializer.DEFAULT_LAX_READABLE, but only
if the message is actually logged.
Example:
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:
7.27 - HTTP Status Codes
By default, a 200 (OK) status is automatically set as the HTTP status when a Java method executes successfully.
Other status codes can be generated by throwing a RestException with a
specific HTTP status code, or calling HttpServletResponse.setStatus(int).
Non-OK (200) status codes are automatically triggered by the following conditions:
| 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 |
7.28 - Overloading HTTP Methods
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.
7.29 - Built-in Parameters
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. |
7.30 - Custom Serializers and Parsers
A very easy-to-use API is provided for defining your own serializers and parsers at both the servlet and method levels.
The following examples show a custom serializer and parser defined at the method level.
It's the
7.31 - Using with OSGi
Since REST servlets are basically just
The following code shows how to register your REST servlets in an OSGi
7.32 - Remoteable Proxies
The Remoteable Service API allows for client side code to use interface proxies for calling methods on POJOs on the server side.
Proxy interfaces are retrieved using the RestClient.getRemoteableProxy(Class)
method.
The remoteable servlet is a specialized subclass of RestServlet that provides a
full-blown REST interface for calling remoteable services (e.g. POJOs) remotely.
The following simplified example shows how a method on a POJO on a server can be called through an interface on a client...
The requirements for an interface method to be callable through the remoteable service are:
- The method must be public.
- The parameter and return types must be serializable and parsable.
-
The method can optionally throw any
Throwablethat has a public no-arg or single-arg-string constructors.
There are automatically recreated on the client side when thrown on the server side.
The client side code for invoking this method is shown below...
Under the covers, this method call gets converted to a REST POST.
HTTP POST http://localhost:10000/remoteable/org.apache.juneau.examples.rest.IAddressBook/createPerson 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.
To define a remoteable interface, simply add the @Remoteable
annotation to your interface class.
This annotation tells the framework that all methods defined on this interface can be executed remotely.
It can be applied to super-interfaces, super-classes, etc..., and exposes the methods at whatever level it is
defined.
There are two ways to expose remoteable proxies on the server side:
-
Extending from
RemoteableServlet. -
Using a
@RestMethod (name=PROXY )
The RemoteableServlet class is a simple specialized servlet with an abstract
getServiceMap() method to define the server-side POJOs:
The
You simply define a Java method whose return type is an interface, and return the implementation of that
interface:
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 remoteable service can be made directly from
a browser with no coding involved.
The parameters and return types of the Java methods can be any of the supported serializable and parsable types.
This ends up being WAY more flexible than other proxy interfaces since Juneau can handle so may POJO types
out-of-the-box.
Most of the time you don't even need to modify your existing Java implementation code.
7.32.1 - Client Side
Remoteable interface proxies are retrieved through the existing RestClient
class.
It may seem that the client-side code would need to be complex.
In reality, it builds upon existing serializing, parsing, and REST capabilities in Juneau resulting in very
little additional code.
The entire code for the RestClient.getRemoteableProxy(Class) method is shown below:
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.
7.32.2 - Server Side
The server side is only slightly more complex, but boasts useful debugging and discovery capabilities.
The RemoteableServlet class is an implementation of
RestServlet that provides a REST interface for invoking calls on POJOs.
The RemoteableServlet class is abstract and must implement a single method for providing the set
of POJOs to expose as remote interfaces.
The samples bundle includes a sample implementation of a remoteable service that can be used to interact with
the address book POJO also included in the bundle.
The method that must be implemented is RemoteableServlet.getServiceMap()
that simply returns a mapping of Java interfaces (or classes) to POJO instances.
Since this class is a servlet, and can be deployed as such.
In the sample code, it's listed as a child resource to org.apache.juneau.rest.samples.RootResources
which makes it available under the URL /sample/remoteable.
If you point your browser to that URL, you get a list of available interfaces:
http://localhost:10000/remoteable
Clicking the hyperlinks on each shows you the list of methods that can be invoked on that service.
Note that the IAddressBook link shows that you can only invoke methods defined on that
interface, whereas the AddressBook link shows ALL public methods defined on that class.
IAddressBook
http://localhost:10000/remoteable/org.apache.juneau.examples.addressbook.IAddressBook
Since AddressBook extends from LinkedList, you may notice familiar collections
framework methods listed.
AddressBook
http://localhost:10000/remoteable/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/remoteable/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/remoteable/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/remoteable/org.apache.juneau.examples.addressbook.IAddressBook/findPerson(int)?method=POST&body=@(3)
When specifying the POST body as a &body parameter, the method arguments should be in UON
notation.
See UonSerializer for more information about this encoding.
Usually you can also pass in JSON if you specify &Content-Type=text/json in the URL parameters
but passing in unencoded JSON in a URL may not work in all browsers.
Therefore, UON is preferred.
The hyperlinks on the method names above lead you to a simple form-entry page where you can test passing parameters in UON notation as URL-encoded form posts.
Sample form entry page
Sample form entry page results
7.32.3 - @Remoteable Annotation
What if you want fine-tuned control over which methods are exposed in an interface instead of just all public
methods?
For this, the @Remoteable annotation is provided.
It can be applied to individual interface methods to only expose those methods through the remoteable servlet.
For example, to expose only the first 2 methods in our IAddressBook interface...
On the server side, the option to restrict access to only annotated methods is defined through a property:
The
7.33 - Swagger
7.34 - Using with Spring and Injection frameworks
The Juneau REST server API is compatible with dependency injection frameworks such as Spring.
The important class is the RestResourceResolver class which is used
to resolve child servlet/resource implementation classes inside parent contexts.
In other words, it's used for resolving @RestResource.children() instances.
The general approach starts with defining a resolver that uses the Spring application context for resolution:
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:
7.35 - Using HTTP/2 features
Juneau is built as a veneer on top of the Servlet API, allowing you to use low-level Servlet APIs
whenever needed.
This allows you to take advantage of the newest HTTP/2 features implemented in the new Servlet 4.0
specification.
Coming soon (sorry)
7.36 - Predefined Label Beans
The org.apache.juneau.rest.labels package contains some reusable beans that are useful for
creating linked items in HTML views.
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:
The BeanDescription class provides a simple view
of a bean and it's properties.
This example renders the following:
The @HtmlLink annotation can also be useful
for rendering custom hyperlinks:
This example renders the following consisting of a list of hyperlinks:
See Also:
7.37 - Other Notes
-
Subclasses can use either
GenericServlet.init(ServletConfig)orGenericServlet.init()for initialization just like any other servlet. -
The
X-Response-Headers header can be used to pass through header values into the response. The value should be a URL-encoded map of key-value pairs. For example, to add a"Refresh: 1" header to the response to auto-refresh a page, the following parameter can be specified:"/sample?X-Response-Headers={Refresh=1}"
8 - juneau-rest-server-jaxrs
Maven Dependency
Java Library
juneau-rest-server-jaxrs-7.2.0.jar
OSGi Module
org.apache.juneau.rest.server_7.2.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.
8.1 - Juneau JAX-RS Provider
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:
- Use existing Juneau serializers and parsers for converting streams to POJOs and vis-versa.
-
Use annotations to specify filters and properties using the
@RestMethodandJuneauProviderannotations.
What you can't do with the Juneau JAX-RS provider classes:
-
Specify or override serializers/parsers at the Java class and method levels.
JAX-RS does not provide the capability to use different providers for the same media types at the class or method levels. - Specify or override filters and properties at the Java class level.
-
Default stylesheets for the
HtmlDocSerializerclass.
It will produce HTML, but it won't contain any styles applied. -
The ability to specify HTTP method, headers, and content using GET parameters.
These make debugging REST interfaces using only a browser possible. - Class or method level encoding.
- Class or method level guards.
- Class or method level converters.
The Juneau JAX-RS provider API consists of the following classes:
-
BaseProvider- The base provider class that implements the JAX-RSMessageBodyReaderandMessageBodyWriterinterfaces. -
JuneauProvider- Annotation that is applied to subclasses ofBaseProviderto 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 theBasicRestServletclass.
For the most part, when using these components, you'll either use the existing
9 - juneau-rest-client
Maven Dependency
Java Library
juneau-rest-client-7.2.0.jar
OSGi Module
org.apache.juneau.rest.client_7.2.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.
Features
-
Converts POJOs directly to HTTP request message bodies using
Serializerclasses. -
Converts HTTP response message bodies directly to POJOs using
Parserclasses. -
Exposes the full functionality of the Apache HttpClient API by exposing all methods defined on the
HttpClientBuilderclass. - Provides various convenience methods for setting up common SSL and authentication methods.
- Provides a fluent interface that allows you to make complex REST calls in a single line of code.
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.jarhttpcore-4.4.1.jarhttpmime-4.5.jar
Example:
Notes:
-
The
RestClientclass exposes all the builder methods on the Apache HttpClientHttpClientBuilderclass.
Use these methods to provide any customized HTTP client behavior.
9.1 - Interface Proxies Against 3rd-party REST Interfaces
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.
Similar in concept to remoteable services defined above, but in this case we simply define our interface with special annotations that tell us how to convert input and output to HTTP headers, query parameters, form post parameters, or request/response bodies.
The call above translates to the following REST call:
POST http://hostname/some/rest/interface/method?debug=true HTTP/1.1 Accept: application/json Content-Type: application/json E-Tag: 475588d4-0b27-4f56-9296-cc683251d314 { "foo": "bar", "baz": 123, "qux": true}
The Java method arguments can be annotated with any of the following:
-
Query- A URL query parameter.
The argument can be any of the following types:- Any serializable POJO
- Converted to text using
UonPartSerializer.serialize(HttpPartType,Object). Map<String,Object>- Individual name-value pairs.
Values are converted to text usingUonPartSerializer.serialize(HttpPartType,Object).String- Treated as a query string.
- Any serializable POJO
- Converted to text using
-
QueryIfNE- Same as@Query except skips the value if it's null/empty. -
FormData- A form-data parameter.
Note that this is only available if the HTTP method isPOST.
The argument can be any of the following types:- Any serializable POJO
- Converted to text using
UonPartSerializer.serialize(HttpPartType,Object). NameValuePairs- Individual name-value pairs.Map<String,Object>- Individual name-value pairs.
Values are converted to text usingUonPartSerializer.serialize(HttpPartType,Object).
- Any serializable POJO
- Converted to text using
-
FormDataIfNE- Same as@FormData except skips the value if it's null/empty. -
Header- A request header.
The argument can be any of the following types:- Any serializable POJO
- Converted to text using
UonPartSerializer.serialize(HttpPartType,Object). Map<String,Object>- Individual name-value pairs.
Values are converted to text usingUonPartSerializer.serialize(HttpPartType,Object).
- Any serializable POJO
- Converted to text using
-
HeaderIfNE- Same as@Header except skips the value if it's null/empty. -
Body- The HTTP request body.
The argument can be any of the following types:- Any serializable POJO
- Converted to text/bytes using the
Serializerregistered with theRestClient. Reader- Raw contents of reader will be serialized to remote resource.InputStream- Raw contents of input stream will be serialized to remote resource.HttpEntity- Bypass Juneau serialization and pass HttpEntity directly to HttpClient.NameValuePairs- Converted to a URL-encoded FORM post.
- Any serializable POJO
- Converted to text/bytes using the
The return type of the Java method can be any of the following:
-
void - Don't parse any response.
Note that the method will still throw a runtime exception if an error HTTP status is returned. -
Any parsable POJO
- The body of the response will be converted to the POJO using the parser defined on the
RestClient. -
HttpResponse- Returns the rawHttpResponsereturned by the innerHttpClient. -
Reader- Returns access to the raw reader of the response.
Note that if you don't want your response parsed as a POJO, you'll want to get the response reader directly. -
InputStream- Returns access to the raw input stream of the response.
9.2 - SSL Support
The simplest way to enable SSL support in the client is to use the
RestClientBuilder.enableSSL(SSLOpts) method and one of the predefined
SSLOpts instances:
SSLOpts.DEFAULT- Normal certificate and hostname validation.SSLOpts.LAX- Allows for self-signed certificates.
Example:
This is functionally equivalent to the following:
RestClientBuilder builder = RestClient.
More complex SSL support can be enabled through the various HttpClientBuilder
methods defined on the class.
9.2.1 - SSLOpts Bean
The SSLOpts class itself is a bean that can be created by the
parsers.
For example, SSL options can be specified in a config file and retrieved as a bean using the
Config class.
Contents of MyConfig.cfg
Code that reads an SSLOpts bean from the config file
9.3 - Authentication
9.3.1 - BASIC Authentication
The RestClientBuilder.basicAuth(String,int,String,String) method
can be used to quickly enable BASIC authentication support.
Example:
This is functionally equivalent to the following:
RestClientBuilder builder = RestClient.
9.3.2 - FORM-based Authentication
The RestClientBuilder class does not itself provide FORM-based
authentication since there is no standard way of providing such support.
Typically, to perform FORM-based or other types of authentication, you'll want to create your own
subclass of RestClientBuilder and override the
RestClientBuilder.createHttpClient() method to provide an
authenticated client.
The following example shows how the JazzRestClient class provides FORM-based
authentication support.
9.3.3 - OIDC Authentication
The following example shows how the JazzRestClient class provides OIDC authentication
support.
9.4 - Using Response Patterns
One issue with REST (and HTTP in general) is that the HTTP response code must be set as a header before the
body of the request is sent.
This can be problematic when REST calls invoke long-running processes, pipes
the results through the connection, and then fails after an HTTP 200 has already been sent.
One common solution is to serialize some text at the end to indicate whether the long-running process
succeeded (e.g.
The RestClient class has convenience methods for scanning the
response without interfering with the other methods used for retrieving output.
The following example shows how the RestCall.successPattern(String)
method can be used to look for a SUCCESS message in the output:
Example:
The RestCall.failurePattern(String) method does the opposite.
It throws an exception if a failure message is detected.
Example:
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
Example:
Using response patterns does not affect the functionality of any of the other methods
used to retrieve the response such as RestCall.getResponseAsString()
or RestCall.getResponse(Class).
HOWEVER, if you want to retrieve the entire text of the response from inside the match methods,
use RestCall.getCapturedResponse() since this method will not absorb
the response for those other methods.
9.5 - Piping Response Output
The RestCall class provides various convenience pipeTo()
methods to pipe output to output streams and writers.
If you want to pipe output without any intermediate buffering, you can use the
RestCall.byLines() method.
This will cause the output to be piped and flushed after every line.
This can be useful if you want to display the results in real-time from a long running process producing
output on a REST call.
Example:
9.6 - Debugging
Use the RestClientBuilder.debug() method to enable logging for HTTP requests
made from the client.
Under-the-covers, this is simply a shortcut for adding the RestCallLogger.DEFAULT
interceptor to the client.
This causes the following output to be generated by the Java org.apache.juneau.rest.client
logger at
=== HTTP Call (outgoing) ======================================================= === REQUEST === POST http://localhost:10000/testUrl HTTP/1.1 ---request headers--- Debug: true No-Trace: true Accept: application/json ---request entity--- Content-Type: application/json ---request content--- {"foo":"bar","baz":123} === RESPONSE === HTTP/1.1 200 OK ---response headers--- Content-Type: application/json;charset=utf-8 Content-Length: 21 Server: Jetty(8.1.0.v20120127) ---response content--- {"message":"OK then"} === END ========================================================================
This setting also causes a Debug: true header value to trigger logging of the request on the
server side as well.
=== HTTP Request (incoming) ==================================================== HTTP POST /testUrl ---Headers--- Host: localhost:10000 Transfer-Encoding: chunked Accept: application/json Content-Type: application/json User-Agent: Apache-HttpClient/4.5 (Java/1.6.0_65) Connection: keep-alive Debug: true Accept-Encoding: gzip,deflate ---Default Servlet Headers--- ---Body--- {"foo":"bar","baz":123} === END ========================================================================
9.7 - Logging
Use the RestClientBuilder.logTo(Level,Logger) and
RestCall.logTo(Level,Logger) methods to log HTTP calls.
These methods will cause the HTTP request and response headers and body to be logged to the specified logger.
Example:
The method call is ignored if the logger level is below the specified level.
Customized logging can be handled by sub-classing the RestCallLogger
class and using the RestCall.interceptor(RestCallInterceptor) method.
9.8 - Interceptors
The RestClientBuilder.interceptors(RestCallInterceptor...) and
RestCall.interceptor(RestCallInterceptor) methods can be used to
intercept responses during specific connection lifecycle events.
The RestCallLogger class is an example of an interceptor that uses
the various lifecycle methods to log HTTP requests.
9.9 - Other Useful Methods
The RestClientBuilder.rootUrl(Object) method can be used to specify a
root URL on all requests so that you don't have to use absolute paths on individual calls.
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.
10 - juneau-microservice-server
Maven Dependency
Java Library
juneau-microservice-server-7.2.0.jar
OSGi Module
org.apache.juneau.microservice.server_7.2.0.jar
Microservice Starter Project
my-microservice.zip
Juneau Microservice is an API for creating stand-alone executable jars that can be used to start lightweight configurable REST interfaces with all the power of the Juneau REST server and client APIs.
10.1 - Microservice Introduction
The Microservice API consists of a combination of the Juneau Core, Server, and Client APIs and an embedded
Eclipse Jetty Servlet Container.
It includes all libraries needed to execute in a Java 1.7+ environment.
Features include:
- An out-of-the-box zipped Eclipse project to get started quickly.
- Packaged as a simple executable jar and configuration file.
- All the power of the Juneau ecosystem for defining REST servlets and clients with the ability to serialize and parse POJOs as HTML, JSON, XML, RDF, URL-Encoding, and others.
- An extensible API that allows you to hook into various lifecycle events.
- Simple-to-use APIs for accessing manifest file entries, command-line arguments, and external configuration file properties.
- Predefined REST resources for configuring microservice and accessing log files.
The juneau-microservice-server library consists of the following classes:
-
Microservice- Defines basic lifecycle methods for microservices in general.-
RestMicroservice- Defines additional lifecycle methods for REST microservices.
Starts up an externally-configured Jetty server, registers servlets, and sets up other features such as logging.
-
10.2 - Getting Started
The
10.2.1 - Installing in Eclipse
Follow these instructions to create a new template project in Eclipse.
-
Download the latest microservice-project zip file (e.g.
my-microservice.zip ). -
In your Eclipse workspace, go to File -> Import -> General -> Existing Projects into Workspace
and select the zip file and click Finish.
-
In your workspace, you should now see the following project:
The important elements in this project are:
-
RootResources.java - The top-level REST resource.
This class routes HTTP requests to child resources:
@RestResource ( path="/" , title="My Microservice" , description="Top-level resources page" , htmldoc=@HtmlDoc ( widgets={ ContentTypeMenuItem.class , StyleMenuItem.class }, navlinks={"options: servlet:/?method=OPTIONS" } ), children={ HelloWorldResource.class , ConfigResource.class , LogsResource.class } )public class RootResourcesextends BasicRestServletJenaGroup {// No code } -
my-microservice.cfg - The external configuration file.
Contains various useful settings.
Can be used for your own resource configurations.
#======================================================================================================================= # Basic configuration file for REST microservices # Subprojects can use this as a starting point. #======================================================================================================================= # What to do when the config file is saved. # Possible values: # NOTHING - Don't do anything. (default) # RESTART_SERVER - Restart the Jetty server. # RESTART_SERVICE - Shutdown and exit with code '3'. saveConfigAction =RESTART_SERVER #======================================================================================================================= # Jetty settings #======================================================================================================================= [Jetty] # Path of the jetty.xml file used to configure the Jetty server. config =jetty.xml # Resolve Juneau variables in the jetty.xml file. resolveVars =true # Port to use for the jetty server. # You can specify multiple ports. The first available will be used. '0' indicates to try a random port. # The resulting available port gets set as the system property "availablePort" which can be referenced in the # jetty.xml file as "$S{availablePort}" (assuming resolveVars is enabled). port =10000,0,0,0 #======================================================================================================================= # REST settings #======================================================================================================================= [REST] # Stylesheet to use for HTML views. # The default options are: # - servlet:/styles/juneau.css # - servlet:/styles/devops.css # Other stylesheets can be referenced relative to the servlet package or working directory. stylesheet =servlet:/styles/devops.css #======================================================================================================================= # Console settings #======================================================================================================================= [Console] enabled =true # List of available console commands. # These are classes that implements ConsoleCommand that allow you to submit commands to the microservice via # the console. # When listed here, the implementations must provide a no-arg constructor. # They can also be provided dynamically by overriding the Microservice.createConsoleCommands() method. commands =org.apache.juneau.microservice.console.ExitCommand, org.apache.juneau.microservice.console.RestartCommand, org.apache.juneau.microservice.console.HelpCommand #======================================================================================================================= # Logger settings #----------------------------------------------------------------------------------------------------------------------- # See FileHandler Java class for details. #======================================================================================================================= [Logging] ...#======================================================================================================================= # System properties #----------------------------------------------------------------------------------------------------------------------- # These are arbitrary system properties that are set during startup. #======================================================================================================================= [SystemProperties] # Configure Jetty for StdErrLog Logging # org.eclipse.jetty.util.log.class = org.eclipse.jetty.util.log.StrErrLog # Configure Jetty to log using java-util logging org.eclipse.jetty.util.log.class =org.apache.juneau.microservice.JettyLogger # Jetty logging level # Possible values: ALL, DEBUG, INFO, WARN, OFF org.eclipse.jetty.LEVEL =WARN derby.stream.error.file =$C{Logging/logDir}/derby-errors.log -
jetty.xml - The Jetty configuration file.
A bare-bones config file that can be extended to use any Jetty features.
<Configure id ="ExampleServer" class ="org.eclipse.jetty.server.Server" ><Set name ="connectors" > <Array type ="org.eclipse.jetty.server.Connector" > <Item> <New class ="org.eclipse.jetty.server.ServerConnector" > <Arg> <Ref refid ="ExampleServer" /> </Arg> <Set name ="port" > $S{availablePort,8080}</Set> </New> </Item> </Array> </Set> <New id ="context" class ="org.eclipse.jetty.servlet.ServletContextHandler" > <Set name ="contextPath" >/</Set> <Call name ="addServlet" > <Arg> org.apache.juneau.microservice.sample.RootResources</Arg> <Arg> /*</Arg> </Call> <Set name ="sessionHandler" > <New class ="org.eclipse.jetty.server.session.SessionHandler" /> </Set> </New> <Set name ="handler" > <New class ="org.eclipse.jetty.server.handler.HandlerCollection" > <Set name ="handlers" > <Array type ="org.eclipse.jetty.server.Handler" > <Item> <Ref refid ="context" /> </Item> <Item> <New class ="org.eclipse.jetty.server.handler.DefaultHandler" /> </Item> </Array> </Set> </New> </Set> <Set name ="requestLog" > <New id ="RequestLogImpl" class ="org.eclipse.jetty.server.NCSARequestLog" > <Set name ="filename" ><Property name ="jetty.logs" default ="$C{Logging/logDir,logs}" /> /jetty-requests.log</Set> <Set name ="filenameDateFormat "> yyyy_MM_dd</Set> <Set name ="LogTimeZone" > GMT</Set> <Set name ="retainDays" > 90</Set> <Set name ="append" > false</Set> <Set name ="LogLatency" > true</Set> </New> </Set> <Get name ="ThreadPool" > <Set name ="minThreads" type ="int" > 10</Set> <Set name ="maxThreads" type ="int" > 100</Set> <Set name ="idleTimeout" type ="int" > 60000</Set> <Set name ="detailedDump" > true</Set> </Get> </Configure>
At this point, you're ready to start the microservice from your workspace.
10.2.2 - Running in Eclipse
The
Go to Run -> Run Configurations -> Java Application -> my-microservice and click Run.
In your console view, you should see the following output:
Running class 'RestMicroservice' using config file 'my-microservice.cfg'. Server started on port 10000 List of available commands: exit -- Shut down service restart -- Restarts service help -- Commands help >
Now open your browser and point to
http://localhost:10000
You have started a REST interface on port 10000.
You can enter the command exit to shut it down.
10.2.3 - Building and Running from Command-Line
The
The easiest way to build your microservice is to run the following from the project root.
mvn clean install
Your target directory should now contain the following files:
my-microservice-1.0.jarmy-microservice.cfgjetty.xml
To start from a command line, run the following command from inside your target directory:
java -jar my-microservice-1.0.jar
You should see the following console output:
Running class 'RestMicroservice' using config file 'my-microservice.cfg'. Server started on port 10000 List of available commands: exit -- Shut down service restart -- Restarts service help -- Commands help >
If you get this error message: java.net.BindException: Address already in use,
then this microservice is already running elsewhere and so it cannot bind to port 10000.
10.3 - Manifest File
The generated
If you open it, you'll see the following:
The
In most cases, this value will always be
However, it is possible to extend this class or implement your own microservice, in which case you'll need
to modify this value to point to the new class.
The
In addition to these predefined manifest entries, you can add your own particular entries to the manifest file and access them through the Manifest API described next.
10.3.1 - Manifest API
The Microservice.getManifest() method is a static method that
can be used to retrieve the manifest file as a ManifestFile.
The ManifestFile class extends ObjectMap,
making it possible to retrieve entries as a wide variety of object types such as java primitives, arrays, collections,
maps, or even POJOs serialized as JSON.
10.4 - Config
The microservice config file is an external INI-style configuration file that is used to configure your microservice.
See Also:
10.4.1 - Config File API
There are 3 primary ways of getting access to the config file.
Microservice.getConfig()
Any initialization-time variables can be used.RestContext.getConfig()
Any initialization-time variables can be used.Example usage:
#------------------------------- # Properties for MyHelloResource #------------------------------- [MyHelloResource] greeting =Hello world! @RestResource (...)public class MyHelloResourceextends BasicRestServlet {// Access config file when initializing fields. private String greeting = getConfig().getString("MyHelloResource/greeting" );// Or access config file in servlet init method. @Override /* Servlet */ public void init() { String greeting = getConfig().getString("MyHelloResource/greeting" ); } }Additional user-defined variables can be defined at this level by adding a
HookEvent.INIThook method and using theRestContextBuilder.vars(Class...)method.-
RestRequest.getConfig()- An instance method to access it from inside a REST method.
Any initialization-time or request-time variables can be used.Example usage:
#----------------------------- # Contents of microservice.cfg #----------------------------- [MyHelloResource] greeting =Hello $RP{person}! localizedGreeting =$L{HelloMessage,$RP{person}} #--------------------------------- # Contents of MyHelloResource.java #--------------------------------- @RestResource ( path="/hello" , messages="nls/Messages" , ... )public class MyHelloResourceextends BasicRestServlet {/** Standard hello message. */ @RestMethod (name=GET , path="/{person}" )public String sayHello(RestRequest req) {return req.getConfig().getString("MyHelloResource/greeting" ); }/** Hello message in users language. */ @RestMethod (name=GET , path="/localized/{person}" )public String sayLocalizedHello(RestRequest req) {return req.getConfig().getString("MyHelloResource/localizedGreeting" ); } }#--------------------------------------- # Contents of nls/Messages_en.properties #--------------------------------------- MyHelloResource.HelloMessage =Hello {0}! Additional user-defined variables can be defined at this level by overriding the
RestContextBuilder.vars(Class...)method.
That
Here's what happens when an HTTP call is made to
-
The HTTP call matches the
/hello path on theMyHelloResource class. -
The HTTP call matches the
/localized/{person} path on thesayLocalizedHello() method. -
The request attribute
person gets assigned the value"Bob" . -
The call to
req.getConfig().getString("MyHelloResource/localizedGreeting") finds the value"$L{HelloMessage,$RP{person}}" . -
The arguments in the
$L{} variable get resolved, resulting in"$L{HelloMessage,Bob}" . -
The
$L{} variable gets resolved to the message"Hello {0}!" in the localized properties file of the servlet based on theAccept-Language header on the request. -
The arguments get replaced in the message resulting in
"Hello Bob!" . -
The resulting message
"Hello Bob!" is returned as a POJO to be serialized to whatever content type was specified on theAccept header on the request.
This particular example is needlessly complex, but it gives an idea of how variables can be used recursively to produce sophisticated results
10.5 - Resource Classes
Now let's take a look at the resource classes themselves.
The top-level page...
http://localhost:10000
...is generated by this class...
-
The title and
description annotations define the titles on the page.
These can be globalized using$L{...} variables, or by defining specially-named properties in the properties file for the resource. -
In this case, the
path annotation defines the context root of your application since it was not specified in the manifest or config file.
Therefore, this resource is mapped tohttp://localhost:10000 . -
The
children annotation make up the list of child resources.
These child resources can be anything that extends fromServlet , although usually they will be subclasses ofBasicRestServletor other resource groups.
If you click the
http://localhost:10000/helloWorld
...which is generated by this class...
10.6 - Predefined Resource Classes
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.
10.7 - RestMicroservice
The RestMicroservice class is the main application entry-point for REST
microservices.
The class hierarchy is:
-
Microservice- Abstract class that defines simple start/stop methods and access to the manifest file, config file, and arguments.-
RestMicroservice- Specialized microservice for starting up REST interfaces using Jetty and specifying REST servlets through the manifest file or config file.
-
Refer to the Javadocs for these class for more information.
10.7.1 - Extending RestMicroservice
This example shows how the RestMicroservice class
can be extended to implement lifecycle listener methods or override existing methods.
We'll create a new class
First, the manifest file needs to be modified to point to our new microservice:
Then we define the following class:
The microservice APIs provide several useful methods that can be used or extended.
See Also:
11 - juneau-examples-core
Archive File
juneau-examples-core-7.2.0.zip
The juneau-examples-core project contains various code examples for using the core APIs.
The project project can be loaded into your workspace by importing the
juneau-examples-core-7.2.0.zip file.
juneau-examples-core install instructions
Download the juneau-examples-core-7.2.0.zip file from the downloads page
(located in the binaries) and import it into your workspace as an existing project:
Select the archive file and import the project:
Once loaded, you should see the following project structure:
The Core library samples are currently a work-in-progress so there's not much here yet. This section will be updated as new code is added.
12 - juneau-examples-rest
Archive File
juneau-examples-rest-7.2.0.zip
The juneau-examples-rest project includes everything you need to start the Samples REST
microservice in an Eclipse workspace.
This project is packaged as a Juneau Microservice project that allows REST resources to be started using embedded Jetty.
juneau-examples-rest install instructions
Download the juneau-examples-rest-7.2.0.zip file from the downloads page
(located in the binaries) and import it into your workspace as an existing project:
Select the archive file and import the project:
Once loaded, you should see the following project structure:
The microservice can be started from the juneau-examples-rest.launch file.
It will start up the microservice on port 10000 which you can then view through a browser:
http://localhost:10000
12.1 - RootResources
The
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.
-
-
Pointing a browser to the resource shows the following:
http://localhost:10000
The
The
RootResources.java
The
These are resources whose paths are direct decendents to the parent resource.
Child resources must be annotated with the @RestResource.path() annotation to
identify the subpath of the child.
Children CAN extend from BasicRestServlet, but it is not a requirement.
Child resources can also be defined programmatically by using the
RestContextBuilder.children(Class[]) method.
Note that these router pages can be arbitrarily nested deep. You can define many levels of router pages for arbitrarily hierarchical REST interfaces.
Let's step back and describe what's going on here:
During servlet initialization of the
If it finds it, it instantiates instances of each class and recursively performs servlet initialization
on them.
It then associates the child resource with the parent by the name specified by the
When a request for the child URL (
It then forwards the request to the child resource for processing.
The request passed to the child resource is the same as if the child resource had been deployed
independently (e.g. path-info, resource-URI, and so forth).
12.2 - HelloWorldResource
The
HelloWorldResource.java
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
- A default OPTIONS method.
- It can be deployed like any servlet.
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
12.3 - SystemPropertiesResource
The
It demonstrates several capabilities including:
-
Using the
@HtmlDocannotation to customize the HTML view. - Defining Swagger documentation through annotations.
- Using Guards to limit access to certain methods.
- Creating form entry pages using HTML5 beans.
SystemPropertiesResource.java
Pointing a browser to the resource shows the following:
http://localhost:10000/systemProperties
Clicking the OPTIONS link shows you the generated Swagger:
http://localhost:10000/systemProperties?method=OPTIONS
Clicking the FORM link shows you the generated form entry page:
http://localhost:10000/systemProperties/formPage
12.4 - MethodExampleResource
The
-
Using the
Redirectobject to perform redirections. - Using the various Java method parameter annotations to retrieve request attributes, parameters, etc.
-
Using the annotation programmatic equivalents on the
RestRequestobject. -
Setting response POJOs by either returning them or using the
RestResponse.setOutput(Object)method.
The resource is provided to show how various HTTP entities (e.g. parameters, headers) can be accessed
as either annotated Java parameters, or through methods on the
MethodExampleResource.java
The class consists of 4 methods:
-
doExample()
The root page.
Performs a simple redirection to thedoGetExample1() method using aRedirectobject. -
example1()
Shows how to use the following annotations: Method returns a POJO to be serialized as the output. -
example2()
Identical todoGetExample1() but shows how to use theRestRequestandRestResponseobjects:RestRequest.getPathMatch()RestRequest.getQuery()RestRequest.getFormData()RestRequest.getHeaders()RestRequest.getMethod()RequestPathMatch.getRemainder()
RestResponse.setOutput(Object)method. -
example3()
Identical todoGetExample1() but uses automatically resolved parameters based on class type.
Juneau automatically recognizes specific class types such as common header types and automatically resolves them to objects for you.
See @RestMethod for the list of all automatically support parameter types, and@RestResource.paramResolvers()for defining your own custom parameter type resolvers.
There's a lot going on in this method.
Notice how you're able to access URL attributes, parameters, headers, and content as parsed POJOs.
All the input parsing is already done by the toolkit.
You simply work with the resulting POJOs.
As you might notice, using annotations typically results in fewer lines of code and are therefore usually preferred over the API approach, but both are equally valid.
When you visit this page through the router page, you can see the top level page:
http://localhost:10000/methodExample
Clicking the first link on the page results in this page:
http://localhost:10000/methodExample/example1/foo/123/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/path-remainder?q1=456&q2=bar
Notice how the conversion to POJOs is automatically done for us, even for non-standard POJOs such as UUID.
Self-documenting design through Swagger OPTIONS pages
One of the main features of Juneau is that it produces OPTIONS pages for self-documenting design (i.e. REST interfaces that document themselves).
Much of the information populated on the OPTIONS page is determined through reflection.
This basic information can be augmented with information defined through:
-
Annotations - An example of this was shown in the
SystemPropertiesResourceexample above.
Localized strings can be pulled from resource bundles using the$Llocalization variable. -
Resource bundle properties - See
MethodExampleResource.propertiesin the source. -
Swagger JSON files with the same name and location as the resource class (e.g.
MethodExampleResource.json).
Localized versions are defined by appending the locale to the file name (e.g.MethodExampleResource_ja_JP.json);
OPTIONS pages are simply serialized Swagger DTO beans.
Localized versions of these beans are retrieved using the
RestRequest.getSwagger() method.
To define an OPTIONS request handler, the BasicRestServlet class defines
the following Java method:
BasicRestServlet.java
The HtmlDocSerializer class
and specified on the resource class annotation:
This simply creates a link that's the same URL as the resource URL appended with
Links using relative or absolute URLs can be defined this way.
Clicking the
http://localhost:10000/methodExample/?method=OPTIONS
This page (like any other) can also be rendered in JSON or XML by using the
12.5 - UrlEncodedFormResource
The
- How to use form entry beans to process form POSTs.
-
How to use the
RestRequest.getClasspathReaderResource(String)method to serve up static files with embedded string variables.
The class is shown below:
UrlEncodedFormResource.java
The localized messages are pulled from the resource bundle:
UrlEncodedFormResource.properties
The
In this case, RestRequest.getResourceTitle() and
RestRequest.getResourceDescription().
Pointing a browser to the resource shows the following:
http://localhost:10000/urlEncodedForm
Entering some values and clicking
http://localhost:10000/urlEncodedForm
Additional Information
-
RestContextBuilder.vars(Class[])- Servlet and request variables. -
RestCallHandler.getSessionObjects(RestRequest)- Var resolver session objects.
12.6 - RequestEchoResource
The
It provides examples of the following:
-
Using the
@RestResource.properties()annotation to set serializer properties. -
Using the
@RestResource.beanFilters()and@RestResource.pojoSwaps()annotations to set serializer transforms. -
Simply passing in an
ObjectMapparameter on the Java method.
This object map contains the modifiable properties on the request.
The class is shown below:
RequestEchoResource.java
Again, there's a lot going on here that's new that requires some explanation.
The
Instead, it contains lots of loops that can cause stack overflow errors if you were to try to serialize it as-is.
Also, you want to look only at the properties defined on the
The @RestResource.properties(),
@RestResopurce.beanFilters(), and
@RestResopurce.pojoSwaps()
annotations are used to set behavior properties on the resource's underlying bean context, serializers,
and parsers.
You're using them here to modify the behavior of serialization for all content types.
The annotations are functionally equivalent to using the RestContextBuilder class,
as follows:
Hypothetical RequestEchoResource.createSerializers() method
Note how the annotations generally require fewer lines of code.
Pointing a browser to the resource shows the following:
http://localhost:10000/echo
This gives you an idea of what kinds of POJO models can be serialized, since you are serializing a regular
old
12.7 - AddressBookResource
The
- How to create RESTful interfaces using only POJOs.
-
How to use the
@Xmland@XmlSchemaannotations to provide XML namespaces and alter how beans are handled by the XML serializer. -
How to use the
@Rdfand@RdfSchemaannotations to provide XML namespaces and alter how beans are handled by the Jena serializers. -
How to use the
@BeanPropertyannotation to alter how bean properties are handled by the serializers. -
How to use the
RestMethod.name()annotation to create overloaded methods beyond the standard GET/PUT/POST/DELETE. - How to augment data in the OPTIONS page.
-
How to use the
RestClientAPI to interact with the REST resource using the same POJOs used to create the server-side API. - How to interact with the REST resource using only a browser.
-
Using the
Traversableconverter to drill down into POJO models. -
Using the
Queryableconverter to provide search/view/sort functionality against POJOs. -
Using the
Introspectableconverter to invoke methods on POJOs. - Using proxy interfaces.
Pointing a browser to the resource shows the following:
http://localhost:10000/addressBook/people
12.7.1 - Classes
The code is straightforward, consisting of the following classes:
-
package-info.java - Used to define XML namespaces for POJOs in this package. -
IAddressBook - An interface describing the address book. -
AddressBook - A data structure consisting of a list ofPersons. -
Person, Address - In-memory representations of people and addresses. -
CreatePerson, CreateAddress - POJOs for creating and updating people and address through the REST interface. -
AddressBookResource - The REST resource class.
- For the sake of brevity, bean properties are defined as public fields instead of the normal getters/setters. Also, the examples are not the most efficient design and are not thread safe.
The
Here you define a default XML and RDF namespaces and URL mappings for namespace short-names used
throughout this package.
It should be noted that these features are entirely optional, and there are often several ways of
defining these namespaces.
package-info.java
Technically since the RDF and XML namespaces used are the same, we didn't need to define them separately
since the RdfCommon.RDF_useXmlNamespaces setting is enabled by default.
We keep them separate here though to show that they can be defined separately.
Our address book uses the following interface:
IAddressBook.java
Notes:
- You interface an interface for our address book so that you can later use it to demonstrate the proxy interface support.
The
AddressBook.java
Notes:
-
The
@Bean (typeName="addressBook" )<addressBook> .
Without this annotation, the element would revert to the generalized<array> tag. -
The separate constructors are implementation specific and are needed because you're going to be
using this class in two ways, since you'll be demonstrating the client code as well as the server
code, and it eliminates having to define separate client-side and server-side POJOs:
- The normal constructor is used to programmatically create this object in the REST servlet code.
- The no-arg constructor is used by the Juneau parsers to construct this object in our client side code.
The
Person.java
Notes:
-
The
prefix="per" annotations override the default"ab" namespace defined on the package.
It applies to this class and all properties of this class. -
The
@Rdf (beanUri=true )uri property as the resource URI for this resource.
This property has special meaning for the RDF serializer.
The RDF serializer uses this property for the value of therdf:resource attribute. -
The
@BeanProperty (swap=CalendarSwap.Medium.class )"MM dd, yyyy" .
This could have also been specified globally on the resource level through theRestResource.properties()annotation.
The
Address.java
Notes:
-
This class shows how the namespace can be overridden at the property level through the
@Xml (prefix="mail" )
The
CreatePerson.java
The
CreateAddress.java
The
AddressBookResource.java
Notes:
-
The
@RestResource.messages() annotation identifiesorg/apache/juneau/samples/addressbook/nls/AddressBookResource.properties as the resource bundle for localized message for this class. -
You are setting
XML_enableNamespaces totrue to enable XML namespaces. By default, XML namespace support is disabled perXmlSerializer.XML_enableNamespaces, so you have to explicitly enable it on our serializers. -
The
XML_autoDetectNamespaces setting is needed to get the XML serializer to addxmlns attributes to the root elements. This causes the XML serializer to scan the POJO objects for namespaces in order to populate the root element. There are other ways to do this, such as explicitly specifying theXML_defaultNamespaceUris setting at either the resource or method level, which might be preferred in high-performance environments. However,XML_autoDetectNamespaces produces the simplest code for our example. -
The
updatePerson() andupdateAddress() methods use a guard to only allow administrators access. For the sample code, the guard does nothing. It's up to the implementer to decide how to restrict access. -
The
updatePerson() andupdateAddress() methods use thePojoRestclass to locate and update individual nodes in a POJO tree using the path remainder on the request. -
The
doInit() method shows an example of an overloaded method using the@RestMethod(name= annotation.INIT ) -
The
getProxy() method shows how to access the AddressBook bean through a proxy interface.
The OPTIONS page uses the servlet resource bundle to specify the labels so that they're globalizable.
AddressBookResource.properties
12.7.2 - Demo
Pointing a browser to the resource shows the results of running the
http://localhost:10000/addressBook
Clicking the
http://localhost:10000/addressBook/people
Notice how the
Also notice how the dates are formatted as readable strings.
This was from the transform you added to the
Let's see what the output looks like in other formats:
JSON
http://localhost:10000/addressBook/people?Accept=text/json&plainText=true
Lax JSON
http://localhost:10000/addressBook/people?Accept=text/json+simple&plainText=true
XML
http://localhost:10000/addressBook/people?Accept=text/xml&plainText=true
Notice how our
Also notice how the
RDF/XML
http://localhost:10000/addressBook/people?Accept=text/xml+rdf+abbrev&plainText=true
Notice how the
Also notice how
Now lets look at the schema outputs that can be rendered that show information about the POJO classes themselves.
HTML Schema
http://localhost:10000/addressBook/people?Accept=text/html+schema
JSON Schema
http://localhost:10000/addressBook/people?Accept=text/json+schema&plainText=true
XML Schema
http://localhost:10000/addressBook/people?Accept=text/xml+schema&plainText=true
Now let's see what else you can do.
Clicking on the first
http://localhost:10000/addressBook/people/1
Clicking on the OPTIONS link on the page shows you the Swagger doc generated from our annotations and resource bundle properties:
http://localhost:10000/addressBook/?method=OPTIONS
12.7.3 - Traversable
Because you added the
http://localhost:10000/addressBook/people/1/addresses/0
http://localhost:10000/addressBook/people/1/addresses/0/street
12.7.4 - Queryable
The
Show only the name and addresses columns
http://localhost:10000/addressBook/people?v=name,addresses
Show only names that start with 'B*'
http://localhost:10000/addressBook/people?s=name=B*
Show only entries with age greater than 60
http://localhost:10000/addressBook/people?s=age>=60
12.7.5 - Introspectable
The
http://localhost:10000/addressBook/people/1/name?invokeMethod=substring(int,int)&invokeArgs=[1,5]
12.7.6 - ClientTest
The
You'll notice that the class is a stand-alone executable that can be invoked as a plain Java process.
ClientTest.java
The output from running this code is the following:
Running client test... Number of entries = 2 Deleted person Barack Obama, response = DELETE successful Deleted person George Walker Bush, response = DELETE successful Number of entries = 0 Created person Barack Obama, uri = http://localhost:10000/addressBook/people/3 Created person George Walker Bush, uri = http://localhost:10000/addressBook/people/4 Created address http://localhost:10000/addressBook/addresses/7 Created address http://localhost:10000/addressBook/addresses/8 Changed name, response = PUT successful New name = Barack Hussein Obama
12.7.7 - Browser Tips
The Juneau architecture is designed to make it easy to debug REST resources using nothing more than a
browser.
The same actions done programmatically in the last section can also be done using URLs.
By default, you can override the HTTP Method and Content through GET parameters, as shown below:
The ability to overload methods is enabled through the
RestResource.allowMethodParam()
12.8 - SampleRemoteableServlet
The
-
Extending the
RemoteableServletclass to create a proxy service. -
Using the
RestClientclass to create remoteable proxy interfaces.
See Also:
12.9 - TempDirResource
The
-
Extending the
DirectoryResourceclass. -
Using the Apache
ServletFileUpload class to handle multi-part form posts. - Using a system property string variable.
-
Using
RestMatchers.
Pointing a browser to the resource shows the following:
http://localhost:10000/tempDir
Pointing a browser to the
http://localhost:10000/tempDir/upload
Submitting a file redirects to the top-level page:
http://localhost:10000/tempDir
TempDirResource.java
12.10 - AtomFeedResource
The
- Using the ATOM Feed DTO API.
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
AtomFeedResource.java
12.11 - DockerRegistryResource
The
-
Accessing a docker registry REST API as POJOs using
RestClient. -
Using the
ResourceDescriptionclass to implement a top-level 'router' page. -
Using the
RestContext.getConfig()method to access external configuration file values.
Pointing a browser to the resource shows the following:
http://localhost:10000/docker
DockerRegistryResource.java
In this example, we're pulling the aside message from an external file:
resources/DockerRegistryResourceAside.html
The Docker registry URL is specified in the
examples.cfg
12.12 - TumblrParserResource
Note: As of March 2018, this resource is known to not work against the Tumblr API.
The
-
Using
RestClientto retrieve information from other REST resources. -
Using
ObjectMapandObjectListto produce generalized POJO models.
Pointing a browser at a Tumblr blog name, such as
http://localhost:10000/tumblrParser/ibmblr
TumblrParserResource.java
12.13 - PhotosResource
The
- How to define custom serializers and parsers at the method level. In this case, you define a serializer and parser to handle images.
The resource consists of a simple registry of images with integer IDs.
http://localhost:10000/photos
It is initialized with a single entry, which can be accessed through a GET request.
http://localhost:10000/photos/cat
PhotosResource.java
12.14 - JsonSchemaResource
The
- Using the JSON Schema DTO API.
The resource consists of a pre-initialized Schema 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
JsonSchemaResource.java
12.15 - SqlQueryResource
The
-
Using the
ResultSetListto serialize database result sets. -
Using
RestContext.getConfig()to access config properties. - Using form entry beans.
The example uses embedded Derby to create a database whose name is defined in the external configuration files.
Pointing a browser to the resource shows the following:
http://localhost:10000/sqlQuery
Running a query results in the following output:
select count(*) from SYS.SYSTABLES; select TABLEID,TABLENAME,TABLETYPE from SYS.SYSTABLES;
SqlQueryResource.java
samples.cfg
12.16 - ConfigResource
The ConfigResource class is a predefined reusable resource.
It provides a REST interface for reading and altering the microservice config file.
Pointing a browser to the resource shows the following:
http://localhost:10000/config
An edit page is provided for altering the raw config file:
http://localhost:10000/config/edit
The Config class is a serializable POJO, which makes the resource
relatively straightforward to implement.
ConfigResource.java
12.17 - LogsResource
The LogsResource class is a reusable predefined resource.
It provides a REST interface for the log files generated by the microservice.
Pointing a browser to the resource shows the following:
http://localhost:10000/logs
12.18 - PetStoreResource
The PetStoreResource class provides examples of the following:
- Summary and detail views of the same beans providing different levels of information.
-
The use of the
HtmlRenderclass. -
The use of the
@BeanProperty(format)annotation. -
The use of the
Queryableinterface.
PetStoreResource.java
Pointing a browser to the resource shows the following:
http://localhost:10000/petstore
Clicking the QUERY link renders the following menu pop-up complete with tooltips:
The STYLES menu item allows you to try out the other default look-and-feels:
Light look-and-feel
Dark look-and-feel
13 - Security Best-Practices
Security is always an ongoing concern in any library. If you discover any security vulnerabilities in this code, please refer to the instructions found here:
13.1 - juneau-marshall
Demarshalling vulnerabilities
One common security vulnerability is the ability to create arbitrary Java object instances through crafted
user input. For example, support for constructing POJOs based on an input attribute defining a
fully-qualified class name like
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
i.e. instead of
Since bean types are defined at compile time, it's impossible to instantiate arbitrary POJOs.
POJO types of generalized input are also inferred through swaps. Again, since the POJO types are hardcoded at compile time, these should not be subject to demarshalling vulnerabilities. However, it is possible to circumvent this through your swap implementation as shown below:
Note that the JsoParser, a thin layer of the Juneau Parser API written on
top of plain-old Java Object Serialization which itself is vulnerable to demarshalling issues.
Due to this, the JSO parser is not included in any of the default REST servlet implementations.
Be especially careful when using this parser, particularly if you want to use it for handing
application/x-java-serialized-object input through REST servlets.
All other parsers (JSON, URL-Encoding, MessagePack, etc...) work the same way in determining POJO types, so should be safe from demarshalling vulnerabilities.
Dependent libraries
When accessing security vulnerabilities of any library, dependent libraries must also be taken into account:
- The JSON, HTML, MsgPack, URL-Encoding, and UON parsers are written from scratch and do not rely on any other parsing technologies.
- The XML and HTML parsers uses the built-in Java StAX parser. This *should* be free from vulnerabilities.
- The RDF parsers rely on Apache Jena 2.7.1.
As of
7.0.1, no known security vulnerabilities exist that affect Juneau at this time.
13.2 - juneau-svl
Care must be used when defining new Vars using the SVL API since mistakes
could potentially expose system properties, environment variables, or even file system files.
For recap, the SVL support allows you to embed variables of the form
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:
-
Varshave two methodsVar.allowNested()andVar.allowRecurse()that can be overridden to prevent recursive processing of string variables. These are bothfalse for the$Rvariable, so the$Fvariable in the result will never get processed and instead be treated as plain text. -
The
$Fvariable only allows you to retrieve files within the JVM starting directory.
Even though the built-in Juneau variables are safe, special care is needed when defining your own custom
variables. If your variable resolves user input in any way, it's HIGHLY recommended that you override the
Var.allowNested() and Var.allowRecurse()
methods to prevent recursive handling of variables.
13.3 - juneau-rest-server
Denial of service attacks can be alleviated through the maxInput()
setting. Arbitrarily-large input will trigger an exception before causing out-of-memory errors.
The default value for this setting is 100MB.
Since the parsers do not use intermediate DOMs and instead parse directly into Java objects, deeply nested data structures will almost always trigger stack overflow errors long before memory consumption becomes an issue. However, this is NOT true of the RDF parsers that use an intermediate DOM. If parsing RDF, you may want to consider lowering the max-input value above.
14 - Release Notes
What's new in each release
7.1.1 (TBD)
TBD
juneau-marshall
-
Fixed bug where
@Bean (typeName) - Fixed bug where HTML-Schema was not being rendered correctly.
juneau-server
-
Simplified
@RestResource(swagger)and@RestMethod(swagger)annotations. -
Fixed bug in
UriResolverwhen request path info had special characters. -
Fixed bug where incorrect media type was being set on responses (e.g.
text/html+schemainstead oftext/htmlfor schema documents). -
RemoteableServletnow provides a form page for invoking remoteable methods in a browser. -
Newlines were being stripped from
@HtmlDoc (script)
7.2.0 (TBD)
Version 7.2.0 is a major update with major implementation refactoring across all aspects of the product.
juneau-marshall
-
Significant improvements made to the internals of the Serializer and Parser classes.
-
Caching improvements on serializers and parsers have reduced execution time of the core
JUnits by approximately 1/3.
The 17000+ JUnit tests now execute in less than 10 seconds and have a cache-reuse hit rate of 98% (164104 serializers/parsers/bean-contexts retrieved, but only 1801 created from scratch). -
All the various separate
Contextclasses (e.g.JsonSerializerContext) have been folded into their respective serializer or parser classes (e.g.JsonSerializer).
Additionally, these classes are their own bean contexts.
For example, the class hierarchy ofJsonSerializeris now: AllContextobjects are thread-safe and read-only. -
Session objects also now have a consistent class hierarchy.
For example, the class hierarchy ofJsonSerializerSessionis now: Session objects are transient objects that live for the duration of a single parse. -
Builder objects also now have a consistent class hierarchy.
For example, the class hierarchy ofJsonSerializerBuilderis now: Builder objects are used for building up and creatingContextobjects. -
The
PropertyStoreclass has been completely rewritten. It is now a read-only configuration store build using thePropertyStoreBuilderclass.
The previousPropertyStoreclass was overly-complicated with many read/write locks to ensure thread-safety.
The new design shifts to a builder-based model with read-onlyPropertyStoreobjects that can be used as hash keys.
-
Caching improvements on serializers and parsers have reduced execution time of the core
JUnits by approximately 1/3.
-
Improvements to the HTTP-Part APIs.
The existingPartSerializer/PartParserclasses have been replaced with the following all located in the neworg.apache.juneau.httppartpackage: Code for marshalling of parts have been removed from the URL-Encoding serializers and parsers. -
ContextBuilder.property(String,Object)renamed toContextBuilder.set(String,Object). -
ResourceFinderclass has been replaced with the following: -
New methods on
SerializerSession: -
New methods on
ParserSession: -
New
Parser.PARSER_unbufferedsetting allows you to disable internal buffering on the JSON and UON parsers so that they can be used to read continous streams of objects. -
New
JsonParser.JSON_validateEndandUonParser.UON_validateEndsettings allow you to control whether we validate that there is no garbage at the end of the parsed input. -
New
Parser.PARSER_autoCloseStreamssetting allows input streams and readers passed into parsers to be automatically closed after parsing. -
Syntax changed on unswap method on
Surrogateclasses.
It's now a regular method instead of a static method. -
@Swapannotation can now be used withSurrogateclasses. - New support for POJO Builders.
juneau-svl
- New variables:
-
Variables moved from
juneau-microservice :
juneau-config
-
The Config API has been completely revamped.
New features include:- Support for pluggable storage.
- File-system watcher integration support.
Changes made to file system files now automatically reflected in configurations and interface proxies. - New builder-based design.
juneau-dto
-
Enhancements to Swagger DTO:
- New methods for setting and retrieving properties via name:
-
Support for setting non-standard fields such as
"$ref" via getter and setter above. - Setter methods that take in beans and collections of beans can now take in JSON strings.
juneau-rest-server
-
RestServletDefaultrenamed toBasicRestServlet. -
RestServletGroupDefaultrenamed toBasicRestServletGroup. -
The
"$R{...}" variable has been split into the following:"$RA{key1[,key2...]}" -RequestAttributeVar, first non-null value returned byHttpServletRequest.getAttribute(String)."$RF{key1[,key2...]}" -RequestFormDataVar, first non-null value returned byRestRequest.getFormData(String)."$RH{key1[,key2...]}" -RequestHeaderVar, first non-null value returned byRestRequest.getHeader(String)."$RI{key1[,key2...]}" -RestInfoVar, first non-null value returned byRestRequest.getInfoProvider().
The possible values are:"contact" - Value returned byInfo.getContact()"description" - Value returned byRestInfoProvider.getDescription(RestRequest)"externalDocs" - Value returned bySwagger.getExternalDocs()"license" - Value returned byInfo.getLicense()"methodDescription" - Value returned byRestInfoProvider.getMethodDescription(Method,RestRequest)"methodSummary" - Value returned byRestInfoProvider.getMethodSummary(Method,RestRequest)"siteName" - Value returned byRestInfoProvider.getSiteName(RestRequest)"tags" - Value returned bySwagger.getTags()"termsOfService" - Value returned byInfo.getTermsOfService()"title" - SeeRestInfoProvider.getTitle(RestRequest)"version" - SeeInfo.getVersion()
"$RP{key1[,key2...]}" -RequestPathVar, first non-null value returned byRestRequest.getPath(String)."$RQ{key1[,key2...]}" -RequestQueryVar, first non-null value returned byRestRequest.getQuery(String)"$R{key1[,key2...]}" -RequestVar, first non-null other request variable.
The possible values are:"contextPath" - Value returned byRestRequest.getContextPath()"method" - Value returned byRestRequest.getMethod()"methodDescription" - Value returned byRestRequest.getMethodDescription()"methodSummary" - Value returned byRestRequest.getMethodSummary()"pathInfo" - Value returned byHttpServletRequestWrapper.getPathInfo()"requestParentURI" - Value returned byUriContext.getRootRelativePathInfoParent()"requestURI" - Value returned byHttpServletRequestWrapper.getRequestURI()"resourceDescription" - Value returned byRestRequest.getResourceDescription()"resourceTitle" - SeeRestRequest.getResourceTitle()"servletParentURI" - Value returned byUriContext.getRootRelativeServletPathParent()"servletPath" - SeeRestRequest.getServletPath()"servletURI" - SeeUriContext.getRootRelativeServletPath()"siteName" - SeeRestRequest.getSiteName()
-
Refactored the
RestConfigclass intoRestContextBuilder.
Settings onRestContextobjects can now be set declaratively through the following new properties:REST_allowHeaderParamsREST_allowBodyParamREST_allowedMethodParamsREST_renderResponseStackTracesREST_useStackTraceHashesREST_defaultCharsetREST_maxInputREST_paramResolversREST_convertersREST_guardsREST_responseHandlersREST_defaultRequestHeadersREST_defaultResponseHeadersREST_producesREST_consumesREST_clientVersionHeaderREST_resourceResolverREST_loggerREST_callHandlerREST_infoProviderREST_pathREST_contextPathREST_staticFilesREST_staticFileResponseHeadersREST_classpathResourceFinderREST_useClasspathResourceCachingREST_widgetsREST_mimeTypes
-
Support for static files has been simplified and improved.
- Syntax on
@RestResource.staticFiles()has been simplified, and now allows you to specify response headers in the strings. - Response headers for static files can also be configured through
REST_staticFileResponseHeaders. - Static file in-memory caching now configurable through
REST_useClasspathResourceCaching. - Static file retrieval can be customized through
REST_classpathResourceFinder
- Syntax on
-
Eliminated the
RestMatcherReflectingclass.
You can now simply create aRestMatcherthat has a public constructor that takes in the server and method arguments. -
@RestResource.allowMethodParamrenamed toRestResource.allowedMethodParams(). -
@RestMethod.serializersInheritand@RestMethod.parsersInheritreplaced with simplified@RestMethod.inherit(). -
Changes to
RequestFormData:addDefault(Map)takes in aMap<String,Object>instead ofMap<String,String>.
-
Changes to
RequestHeaders:addDefault(Map)takes in aMap<String,Object>instead ofMap<String,String>.
-
Changes to
RequestQuery:addDefault(Map)takes in aMap<String,Object>instead ofMap<String,String>.
-
Changes to
RestContext:getResource(String,Locale)renamed togetClasspathResource(String,Locale)getResourceAsString(String,Locale)renamed togetClasspathResourceAsString(String,Locale)getResource(Class,MediaType,String,Locale)renamed togetClasspathResourceAsString(Class,MediaType,String,Locale)- New method
getClasspathResource(Class,String,Locale). - New method
getClasspathResourceAsString(Class,String,Locale). - New method
getClasspathResource(Class,Class,MediaType,String,Locale). getDefaultRequestHeadersreturns aMap<String,Object>instead ofMap<String,String>.getDefaultRequestHeadersreturns aMap<String,Object>instead ofMap<String,String>.
-
Changes to
RestRequest:getSupportedMediaTypes()replaced withgetConsumes()andgetProduces().getReaderResource(String,boolean,MediaType)renamed togetClasspathReaderResource(String,boolean,MediaType)getReaderResource(String,boolean)renamed togetClasspathReaderResource(String,boolean)getReaderResource(String)renamed togetClasspathReaderResource(String)
-
Changes to
@RestResource:- New
mimeTypes()annotation.
- New
-
Changes to
@RestMethod:- New
consumes()andproduces()for overriding the supported media types inferred from the serializers and parsers.
- New
-
RestCallHandlersplit up intoRestCallHandlerandBasicRestCallHandler -
RestInfoProvidersplit up intoRestInfoProviderandBasicRestInfoProvider -
RestLoggersplit up intoRestLogger,BasicRestLoggerandNoOpRestLogger -
RestResourceResolverSimplerenamed toBasicRestResourceResolver - Introduced the following classes that helps make the code more understandable:
-
Eliminated the
@Messagesand@PropertiesREST java method parameter annotations.
These aren't needed anymore since you can just pass inMessageBundleandRestRequestPropertiesas unannotated parameters. -
Revamped the
RestInfoProviderclass. - New builder classes:
-
RestResponse.getNegotiatedOutputStream()now returns aFinishableServletOutputStreamandRestResponse.getNegotiatedWriter()now returns aFinishablePrintWriterthat allows you to finish the output without closing the stream.
TheDefaultHandlerclass now callsfinish()instead ofclose()on the stream. -
Added the following annotations to the
BasicRestServletclass (which were previously defined on theResource@RestResource ( htmldoc=@HtmlDoc ( navlinks={"up: request:/.." ,"options: servlet:/?method=OPTIONS" }, stylesheet="$C{REST/stylesheet,servlet:/styles/devops.css}" ),// Optional external configuration file. config="$S{juneau.configFile}" )
juneau-rest-client
-
New configuration property
RestClient.RESTCLIENT_queryand builder methodRestClientBuilder.query(String,Object). -
API changes to replace
PartSerializerwithHttpPartSerializer.
The default value is nowSimpleUonPartSerializerwhich will serialize strings as plain-text and collections/arrays as comma-delimited lists.
We decided to change the default behavior in favor of practicality over purity. -
New methods on
RestCallclass: -
RestCallandRestClientnow implement theCloseableinterface.
juneau-microservice
-
ResourceandResourceGroupclasses removed.BasicRestServletandBasicRestServletGroupcan be used instead. -
ResourceJenaandResourceJenaGroupclasses renamed toBasicRestServletJenaandBasicRestServletJenaGroup.
7.0.1 (Dec 24, 2017)
This release is a minor update. It includes the following prereq updates:
- Apache HttpClient: 4.5.3 to 4.5.4
- Eclipse Jetty: 9.4.6.v20170531 to 9.4.8.v20171121
juneau-marshall
- New static
create()methods for builders on serializers and parsers.
This simplifies the syntax of creation of serializers and parsers by scratch.// Old way JsonSerializer s1 =new JsonSerializerBuilder().ws().build();// New way JsonSerializer s2 = JsonSerializer.create ().ws().build();
The same static create methods have also been added to the following classes:SerializerGroup.create()ParserGroup.create()EncoderGroup.create()RestClient.create()ConfigFile.create()
-
The order of the parameters in
SerializerSession.serialize(Object,Object)has been change to matchSerializer.serialize(Object,Object). - Fixed some bugs in the XML parser related to whitespace and comments.
juneau-svl
- New methods on
Varclass to restrict when nested and embedded variables are resolved.
juneau-rest-server
-
New
@RestResource.maxInput()and@RestMethod.maxInput()for alleviating potential DoS attacks.
juneau-microservice-server
-
New pluggable console commands.
When you start up the microservice, you'll now see the following:Running class 'RestMicroservice' using config file 'examples.cfg'. Server started on port 10000 List of available commands: exit -- Shut down service restart -- Restarts service help -- Commands help echo -- Echo command > help help NAME help -- Commands help SYNOPSIS help [command] DESCRIPTION When called without arguments, prints the descriptions of all available commands. Can also be called with one or more arguments to get detailed information on a command. EXAMPLES List all commands: > help List help on the help command: > help help >
Commands are pluggable and extensible through the config file.
#======================================================================================================================= # Console settings #======================================================================================================================= [Console] enabled =true # List of available console commands. # These are classes that implements ConsoleCommand that allow you to submit commands to the microservice via # the console. # When listed here, the implementations must provide a no-arg constructor. # They can also be provided dynamically by overriding the Microservice.createConsoleCommands() method. commands =org.apache.juneau.microservice.console.ExitCommand, org.apache.juneau.microservice.console.RestartCommand, org.apache.juneau.microservice.console.HelpCommand - New classes:
- New methods on
Microservice
- Console input reader and output writer can now be overridden.
- Console strings are now internationalized.
7.0.0 (Oct 25, 2017)
This release ups the Java prerequisite to Java 7.
juneau-marshall
-
New class
HttpMethodNamewith valid static string HTTP method names.
juneau-dto
-
Class
org.apache.juneau.dto.Linkrenamed toLinkString. Helps avoid confusion since there are other Link classes in the library.
juneau-rest-server
-
Annotation
@HtmlDoc (links)navlinks. -
New annotation
@HtmlDoc.head().
Allows you to specify arbitrary HTML content in the<head> section of the page. -
Removed annotation
@HtmlDoc (favIcon)
This was a discouraged way of defining fav-icons anyway, and with the addition of@HtmlDoc (head)head={
"<link rel='icon' href='$U{servlet:/htdocs/juneau.png}'/>" } -
Removed several of the HTMLDOC-related methods from the
RestResponse/RestConfig/RestContextclasses and moved it into the newHtmlDocBuilderclass.
6.4.0 (Oct 5, 2017)
The major change in this release is the project structure.
The library now consists of the following artifacts found in the Maven group "org.apache.juneau":
| 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:
|
|
juneau-marshall
-
Improvements to swap support.
- New
@Swapannotation.
Replaces the@Pojoand@BeanProperty.swap()annotations. - Support for per-media-type swaps.
Programmatic example:@Swap (MyJsonOnlySwap.class )public class MyPojo {}public class MyJsonOnlySwapextends PojoSwap<MyPojo,String> {public MediaType[] forMediaTypes() {return MediaType.forStrings ("*/json" ); }public String swap(BeanSession session, MyPojo o)throws Exception {return "It's JSON!" ; }
Annotated example:@Swap (impl=ToStringSwap.class , mediaTypes="*/json" )public class MyBean { ... }public class ToStringSwapextends PojoSwap<Object,String> {public String swap(BeanSession session, Object o)throws Exception {return o.toString(); } } - Support for templated swaps which provide additional context information for a swap.
The following is an example of a templated swap class used to serialize POJOs to HTML using FreeMarker:// Our abstracted templated swap class. public abstract class FreeMarkerSwapextends PojoSwap<Object,Reader> {public MediaType[] forMediaTypes() {return MediaType.forStrings ("*/html" ); }public Reader swap(BeanSession session, Object o, String template)throws Exception {return getFreeMarkerReader(template, o);// Some method that creates raw HTML. } }@Swap (impl=FreeMarkerSwap.class , template="MyPojo.div.ftl" )public class MyPojo {} - New
@Swapsannotation for defining multiple swaps against the same POJO when they're differentiated by media types:@Swaps ( {@Swap (MyJsonSwap.class ),@Swap (MyXmlSwap.class ),@Swap (MyOtherSwap.class ) } )public class MyPojo {}
- New
-
New
Surrogateinterface for identifying surrogate classes. -
Serializers can now serialize to
StringBuilders. -
Serializers now serialize the contents of
ReadersandInputStreamsdirectly to the output stream or writer.
When used with conjunction withPojoSwaps, this can be used to provide customized output for specific content types.@Pojo (swap=MyBeanSwap.class )public class MyBean {...}public class MyBeanSwapextends PojoSwap<MyBean,Object> {public Object swap(BeanSession session, MyPojo o)throws Exception { MediaType mt = session.getMediaType();if (mt.hasSubType("json" ))return new StringReader("{foo:'bar'}" );// Custom JSON output return o;// Otherwise treat as normal bean } }// Produces "{foo:'bar'}" String json = JsonSerializer.DEFAULT_LAX .toString(new MyBean());
This feature helps with the implementation of language-agnostic template support such as for using FreeMaker to serialize POJOs to HTML. -
SerializerSessionandParserSessionobjects are now reusable if used within the same thread.
This is mostly an internal change and doesn't affect the existing APIs.// Old way (still works) JsonSerializer.DEFAULT .serialize(writer1, pojo1); JsonSerializer.DEFAULT .serialize(writer2, pojo2);// Same, but using a session object SerializerSession session = JsonSerializer.DEFAULT .createSession();try { session.serialize(writer1, pojo1); session.serialize(writer2, pojo2); }finally { session.close(); } -
PojoSwap.swap(BeanSession,Object)andPojoSwap.unswap(BeanSession,Object,ClassMeta)can now throw arbitrary exceptions instead of having to wrap them inSerializeException/ParseException. -
New
CalendarUtilsclass that encapsulates serialization/parsing logic fromCalendarSwapandDateSwap. -
New annotation
Html.anchorText(). -
New methods on
ObjectList: -
New methods on
ObjectMap: -
New methods on
PojoRest: -
Fixed bug where
BeanSession.getMediaType()wasn't returning a value. -
Eliminated the
@Consumes and@Produces annotations.
The supported media types are now passed in through the constructors.
This was changed to eliminate a performance issue where a field could not be set as final because the call togetClass()to retrieve the annotation value could not be called before calling thesuper () -
New class:
PojoMerge -
New doc:
2.6.2 - @Pojo annotation -
New doc:
2.6.5 - Serializing Readers and InputStreams
juneau-dto
-
HtmlElementMixed.children(Object...)can now take in collections of objects. -
The DTO beans can now be serialized to strings of their typical language by calling the
toString()method.
For example,Swagger.toString()produces JSON and the HTML5Form.toString()produces HTML.
juneau-rest-server
-
Revamped and simplified servlet and REST-call lifecycle handling through new
@RestHookannotation.- The
RestServlet.init(ServletConfig)method is now final and can no longer be extended.
Instead, useHookEvent.INITorHookEvent.POST_INITfor initialization. - The following methods on
RestServlethave been removed:init(RestConfig)- UseHookEvent.INITinstead.onSuccess(RestRequest, RestResponse, long)- UseHookEvent.END_CALLinstead.onPreCall(RestRequest)- UseHookEvent.PRE_CALLinstead.onPostCall(RestRequest, RestResponse)- UseHookEvent.POST_CALLinstead.
- The
-
Simplified
MenuItemWidget.
Exposes an abstract methodMenuItemWidget.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 usingHtmlSerializer.DEFAULT. -
RestResourceResolverinstances are now inherited from parent resources to child resources unless explicitly overridden at the child level.
It's also been changed to an interface. - New annotations on
@RestResource:resourceResolver()
Allows you to specify a resource resolver on the servlet context to make it easier to work with dependency injection frameworks.contextPath()-
Allows you to override the context path value inherited from the servlet container.allowHeaderParams()-
Replaces theRestContext.REST_allowHeaderParamssetting.RestResource.allowMethodParam()
Replaces theRestContext.REST_allowMethodParamsetting.allowBodyParam()-
Replaces theRestContext.REST_allowBodyParamsetting.renderResponseStackTraces()-
Replaces theRestContext.REST_xxxsetting.useStackTraceHashes()-
Replaces theRestContext.REST_useStackTraceHashessetting.defaultCharset()-
Replaces theRestContext.REST_defaultCharsetsetting.RestResource.paramFormat()
Replaces theRestContext.REST_paramFormatsetting.
- New annotations on
@RestMethod:defaultCharset()-
Replaces theRestContext.REST_defaultCharsetsetting.RestMethod.paramFormat()
Replaces theRestContext.REST_paramFormatsetting.
- The following implementation classes can now be defined as non-static inner classes of servlets/resources:
-
New tooltip template:
Tooltip -
New dark theme:
-
Stylesheet selection now stored in HTTP session when passed in via
?stylesheetquery parameter. -
New doc:
Lifecycle Hooks -
Eliminated the
RestServletJenaDefaultclass to remove the Jena dependency class on thejuneau-rest-serverartifact.
It's simple enough to simply extendBasicRestServletand add the RDF serializers and parsers.
juneau-microservice
-
The microservice has been significantly modified to be configured via a
jetty.xmlfile for maximum flexibility instead of the hodge-podge of support in the config file.
Top-level servlets should now be defined in the providedjetty.xmlfile. -
New methods on
RestMicroservice: -
New methods on
Microservice: -
New class
JettyLoggerfor directing Jetty logging to the java.util.logging framework. -
New class
DebugResourcefor viewing and generating Jetty thread dumps through REST calls.
org.apache.juneau.rest.examples
-
New example of adding a menu-item widget to the Pet Store resource (including tooltips):
6.3.1 (Aug 1, 2017)
Juneau 6.3.1 is a minor release.
org.apache.juneau
-
PojoQueryimprovements. -
New
RemoteMethod.returns()annotation.
Allows you to specify whether the remote method returns the HTTP body or status code. -
Fixed bugs with
BeanContext.BEAN_includePropertiesandBeanContext.BEAN_excludePropertiessettings. -
New/modified settings in
HtmlDocSerializerContextHTMLDOC_scriptHTMLDOC_styleHTMLDOC_css .HTMLDOC_stylesheetHTMLDOC_cssUrl . Now an array.
-
New
ResourceFinder -
Eliminated the following properties from
HtmlDocSerializerContextHTMLDOC_title ,HTMLDOC_description ,HTMLDOC_description
See below on changes to simplify HTML headers. -
Varimplementations can now throw exceptions and will be converted to""{exceptionMessage}" values.
org.apache.juneau.rest
-
New 'light' stylesheet:
Compared with previous 'devops':
For those nolstalgic for old times, there's also 'original':
-
Simplified the stylesheets and HTML code.
For example, the nav links are now an ordered list of elements which makes rendering as as side-bar (for example) easier to do in CSS. -
Modifications to the following
@HtmlDoc annotations:navlinks()- Now an array of strings instead of a JSON object. Simplified syntax.
For example:
Previous syntax will still work, but you're encouraged to use the simplified syntax.// Old syntax htmldoc=@HtmlDoc ( links="{" +"up:'request:/..'," +"options:'servlet:/?method=OPTIONS'," +"contentTypes:'$W{ContentTypeMenuItem}'," +"styles:'$W{StyleMenuItem}'," +"source:'$C{Source/gitHub}/org/apache/juneau/examples/rest/PetStoreResource.java'" +"}" )// New syntax htmldoc=@HtmlDoc ( navlinks={"up: request:/.." ,"options: servlet:/?method=OPTIONS" ,"$W{ContentTypeMenuItem}" ,"$W{StyleMenuItem}" ,"source: $C{Source/gitHub}/org/apache/juneau/examples/rest/PetStoreResource.java" } )- Several annotations are now arrays of strings instead of simple strings.
Values are simply concatenated with newlines which makes multi-line values cleaner.
Additionally, the
"INHERIT" string literal can be used to combine the value with the value defined on the servlet or parent class. Links can also be inserted at specific index positions.
-
Improvements made to the
WidgetAPI.- You can now add arbitrary CSS and Javascript along with your widgets through new methods:
-
Declaration of widgets moved to
@HtmlDoc.widgets()instead of separately on@RestResource and@RestMethod annotations. -
Widget.getName()now defaults to the simple class name.
So now you can just refer to the class name:"$W{ContentTypeMenuItem}" . -
Renamed widgets:
PoweredByApacheWidget->PoweredByApachePoweredByJuneauWidget->PoweredByJuneau
-
New
MenuItemWidgetcan be used as a starting point for creatint pull-down menu items. -
New
ContentTypeMenuItemwidget that provides a pull-down menu with hyperlinks for all supported languages for that page:
-
Improved
QueryMenuItemwidget that provides a pull-down menu of a search/view/order-by/page form:
Fields are now pre-filled with current query parameters. -
New
StyleMenuItemwidget that provides a pull-down menu with hyperlinks to show the content in the default stylesheets:
-
New/modified annotations on
@HtmlDoc:style()- Renamed fromcss().stylesheet()- Renamed fromcssUrl().
Can now be a comma-delimited list of URLs.script()- Add arbitrary Javascript to page header.
-
Bug fix with
@HtmlDoc.nowrap()so that the setting only applies to the data contents, not the whole page. -
Two convenience methods added to
RestRequest: - Annotations added:
-
Eliminated the
@RestResource.stylesheet()annotation. It's no longer needed now that you can easily specify styles via@Htmldoc . -
Eliminated the following annotations since they are now redundant with
@HtmlDoc.header():title()description()branding()
BasicRestServletclass defines the following default header that can be easily overridden:htmldoc=
Note that the subtitle first tries using the method summary and then the servlet description.@HtmlDoc ( header={"<h1>$R{resourceTitle}</h1>" ,"<h2>$R{methodSummary,resourceDescription}</h2>" ,"<a href='http://juneau.apache.org'><img src='$U{servlet:/htdocs/juneau.png}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/></a>" } ) -
New
$Fvariable resolver for resolving the contents of files in the classpath.
TheDockerRegistryResourceexamples shows how it can be used to pull in a localized file from the classpath to populate the aside section of a page.htmldoc=
@HtmlDoc (// Pull in aside contents from file. aside="$F{resources/DockerRegistryResourceAside.html}" ) -
New
ReaderResource.toCommentStrippedString()method. -
The
bpIncludes()andbpExcludes()annotations on@RestMethod has been replaced with the following: -
Two new variables added to
$Rvariable:"$R{servletClass}" ,"$R{servletClassSimple}"
org.apache.juneau.rest.examples
- Added CONTENT-TYPE and STYLES menu items to most pages.
- Added improved QUERY menu item to PetStore page.
6.3.0 (Jun 30, 2017)
Juneau 6.3.0 is a major update with significant new functionality for defining proxy interfaces against arbitrary 3rd-party REST interfaces.
org.apache.juneau
-
New package:
org.apache.juneau.http. -
Support for dynamic beans. See
@BeanProperty.name(). -
New doc:
2.8 - Virtual Beans -
New doc:
2.13 - Comparison with Jackson -
All parsers now allow for numeric types with
'K' /'M' /'G' suffixes to represent kilobytes, megabytes, and gigabytes.// Example int i = JsonParser.DEFAULT .parse("123M" );// 123MB - New/modified methods on
ConfigFileConfigFile.put(String,String,String,boolean)ConfigFile.put(String,String,Object,Serializer,boolean,boolean)ConfigFile.getObject(String,Type,Type...)ConfigFile.getObject(String,Parser,Type,Type...)ConfigFile.getObject(String,Class)ConfigFile.getObject(String,Parser,Class)ConfigFile.getObject(String,String,Type,Type...)ConfigFile.getObject(String,String,Parser,Type,Type...)ConfigFile.getObject(String,String,Class)ConfigFile.getObject(String,String,Parser,Class)ConfigFile.getObjectWithDefault(String,Object,Type,Type...)ConfigFile.getObjectWithDefault(String,Parser,Object,Type,Type...)ConfigFile.getObjectWithDefault(String,Object,Class)ConfigFile.getObjectWithDefault(String,Parser,Object,Class)
- New ability to interact with config file sections with proxy interfaces with new method
ConfigFile.getSectionAsInterface(String,Class) @BeanPropertyannotation can now be applied to getters and setters defined on interfaces.- New methods on
SerializerSessionandParserSessionfor retrieving context and runtime-override properties:Session.getProperty(String)Session.getProperty(String,String)Session.getProperty(Class,String)Session.getProperty(Class,String,Object)
- New
org.apache.juneau.serializer.PartSerializer
Allows easy user-defined serialization of these objects.
The interface can be used in the following locations: - Across-the-board improvements to the URI-resolution support (i.e. how URIs get serialized).
- New support for resolving URIs with the following newly-recognized protocols:
"context:/..." - Relative to context-root of the application."servlet:/..." - Relative to the servlet URI."request:/..." - Relative to the request URI.
pages=
With these new protocols, we can define them like so:"{up:'$R{requestParentURI}', options:'?method=OPTIONS', upload:'upload'}" links=
The old method of using variables and servlet-relative URIs will still be supported, but using these new protocols should (hopefully) be easier to understand."{top:'context:/', up:'request:/..' ,options:'servlet:/?method=OPTIONS', upload:'servlet:/upload'}"
These protocols work on all serialized URL and URI objects, as well as classes and properties annotated with@URI. - New classes:
- New configuration properties:
SerializerContext.SERIALIZER_uriContextSerializerContext.SERIALIZER_uriRelativitySerializerContext.SERIALIZER_uriResolutionSerializerContext.SERIALIZER_maxIndent
- New support for resolving URIs with the following newly-recognized protocols:
- New annotation property:
@BeanProperty.value().
The following two annotations are considered equivalent:@BeanProperty (name="foo" )@BeanProperty ("foo" ) - Fixed a race condition in ClassMeta.
URLENC_paramFormat has been moved toUonSerializer.UON_paramFormat
This means that arrays and maps are converted to simple comma-delimited lists.- Listener APIs added to serializers and parsers:
SerializerListenerSerializerBuilder.listener(Class)@RestResource.serializerListener()RestConfig.serializerListener(Class)ParserListenerParserBuilder.listener(Class)@RestResource.parserListener()RestConfig.parserListener(Class)RestClientBuilder.listeners(Class,Class)
- The
BeanContext.BEAN_debugflag will now capture parser input and make it available through theParserSession.getInputAsString() - Significant new functionality introduced to the HTML serializer.
Lots of new options for customizing the HTML output.- New
@Html.render()annotation andHtmlRenderclass that allows you to customize the HTML output and CSS style on bean properties:
Annotation can be applied to POJO classes and bean properties. - Several new properties for customizing parts of the HTML page:
HtmlDocSerializerContext.HTMLDOC_titleHtmlDocSerializerContext.HTMLDOC_descriptionHtmlDocSerializerContext.HTMLDOC_brandingHtmlDocSerializerContext.HTMLDOC_headerHtmlDocSerializerContext.HTMLDOC_navHtmlDocSerializerContext.HTMLDOC_asideHtmlDocSerializerContext.HTMLDOC_footerHtmlDocSerializerContext.HTMLDOC_noResultsMessageHtmlDocSerializerContext.HTMLDOC_cssUrlHtmlDocSerializerContext.HTMLDOC_cssHtmlDocSerializerContext.HTMLDOC_template
- New interface
HtmlDocTemplatethat allows full control over rendering of HTML produced byHtmlDocSerializer.
- New
@NamePropertyand@ParentPropertycan now be applied to fields.- New properties on
BeanContext: - New annotation property:
@BeanProperty.format().
org.apache.juneau.rest
- MAJOR enhancements made to the REST API.
-
The
RestRequestclass 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.
-
The un-annotated parameter types that can be passed in through REST Java methods has been significantly expanded.
For reference, the previous supported types were:RestRequest- The request object.HttpServletRequest- The superclass ofRestRequest.RestResponse- The response object.HttpServletResponse- The superclass ofRestResponse.
AcceptAcceptCharsetAcceptEncodingAcceptLanguageAuthorizationCacheControlConnectionContentLengthContentTypeDateExpectFromHostIfMatchIfModifiedSinceIfNoneMatchIfRangeIfUnmodifiedSinceMaxForwardsPragmaProxyAuthorizationRangeRefererTEUserAgentUpgradeViaWarningTimeZoneInputStreamServletInputStreamReaderOutputStreamServletOutputStreamWriterResourceBundle- 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.RequestPathMatch- 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
/** Old way */ @RestMethod (name="*" , path="/example1/{a1}/{a2}/{a3}/*" )public String example1(@Method String method,@Path String a1,@Path int a2,@Path UUID a3,@Query ("p1" )int p1,@Query ("p2" ) String p2,@Query ("p3" ) UUID p3,@Header ("Accept-Language" ) String lang,@Header ("Accept" ) String accept )/** New way */ @RestMethod (name="*" , path="/example2/{a1}/{a2}/{a3}/*" )public String example2( HttpMethod httpMethod, RequestPathParams pathParams, RequestQuery query, AcceptLanguage acceptLanguage, Accept accept ) -
A new annotation
@RestResource.paramResolvers()that allows you to define your own custom Java method parameter resolvers. -
Fixed bug where Writer returned by
RestResponse.getWriter()was not being flushed automatically at the end of the HTTP call. -
New annotations added to
@RestMethod:defaultQuery()defaultFormData()bpIncludes()bpExcludes()
-
Default values on header, query, and form-data annotations:
@Header.def()- Default header value.@Query.def()- Default query parameter value.@FormData.def()- Default form data parameter value.
-
New attributes on
@RestResource: -
New attributes on
@RestMethod: - New string vars:
-
New methods on
RestConfigsetHtmlTitle(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)
-
New methods on
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=trueparameter now works on byte-based serializers by converting the output to hex. -
New classes for widget support:
WidgetPoweredByJuneauWidgetContentTypeLinksColumnWidgetContentTypeLinksRowWidgetQueryWidget
-
devops.csscleaned up. -
Removed a bunch of URL-related methods from
RestRequest. These all have equivalents inRestRequest.getUriContext(). - New annotation attributes:
org.apache.juneau.rest.client
-
New
@Pathannotation for specifying path variables on remoteable interfaces. -
New
@RequestBeanannotation for specifying beans with remoteable annotations defined on properties. -
The following annotations (and related methods on RestCall) can now take
NameValuePairsand beans as input when using"*" as the name.@FormData,@FormDataIfNE,@Query,@QueryIfNE,@Header,@HeaderIfNE,
org.apache.juneau.microservice
org.apache.juneau.examples.rest
- Many code enhancements make to examples to reflect new functionality.
- All pages now render aside comments to help explain what feature they're trying to explain using the
new features that allow you to customize various elements of the page.
6.2.0 (Apr 28, 2017)
Juneau 6.2.0 is a major update.
org.apache.juneau
-
Revamped the serializer, parser classes to use builders for creation.
Serializers and parsers are now unmodifiable objects once they are created.
This is a breaking code change that will require adoption.
/* Creating a new serializer or parser */ // Old way WriterSerializer s =new JsonSerializer().setUseWhitespace(true ).pojoSwaps(BSwap.class ).lock();// New way WriterSerializer s = JsonSerializer.create ().ws().pojoSwaps(BSwap.class ).build();/* Cloning an existing serializer or parser */ // Old way WriterSerializer s = JsonSerializer.DEFAULT_LAX .clone().setUseWhitespace(true ).pojoSwaps(BSwap.class ).lock();// New way WriterSerializer s = JsonSerializer.DEFAULT_LAX .builder().ws().pojoSwaps(BSwap.class ).build(); - Also introduced the following builder classes and related architecture changes to make the built objects unmodifiable:
- Revamped the config file API to use a build:
ConfigFileBuilder - Removed the
Lockable - New
addBeanTypePropertiessetting added to serializers to override theSerializerContext.SERIALIZER_addBeanTypePropertiesHtmlSerializerContext.HTML_addBeanTypePropertiesJsonSerializerContext.JSON_addBeanTypePropertiesMsgPackSerializerContext.MSGPACK_addBeanTypePropertiesUonSerializerContext.UON_addBeanTypePropertiesXmlSerializerContext.#XML_addBeanTypePropertiesRdfSerializerContext.RDF_addBeanTypeProperties
- UON notation serializers and parsers moved into the new
org.apache.juneau.uonpackage. - New
XmlFormat.VOIDformat to identify HTML void elements. - Tweaks to HTML5 support.
- Fixed handling of empty non-void elements in HTML serializer.
- Added
style()override methods to all elements.
- Improvements to Swagger support.
- New
SwaggerBuilderclass. - Fluent-style setters added to the Swagger beans.
- Added Swagger examples
hereorg.apache.juneau.dto.swaggerjavadocs.
- New
- Improvements to
VarResolver.- New
$IFvariable for if-else block logic. $SWITCH- Whitespace wasn't being ignored in some cases.
- New
HtmlParsercan now parse full body contents generated byHtmlDocSerializer.- Parse-args supported added to
MsgPackParserto allow it to be used in remoteable proxies. - Added some convenience classes for constructing collections using a fluent interface:
- New
@Bean.typePropertyName()annotation allows you to specify the name of the"_type" property at the class level. - New methods added to HTML5 container beans:
- New common serializer setting:
SerializerContext.SERIALIZER_abridged - Support for defining interface proxies against 3rd-party REST interfaces.
New packageorg.apache.juneau.remoteablefor all remoteable proxy interface annotations.@Remoteable annotation has been moved to this package. - Updated doc:
6 - Remoteable Services - New doc:
6.1 - Interface proxies against 3rd-party REST interfaces - New URL-encoding serializer setting:
UrlEncodingSerializerContext.URLENC_paramFormat - New methods on
UrlEncodingSerializerBuilder:UrlEncodingSerializerBuilder.paramFormat(String)UrlEncodingSerializerBuilder.plainTextParams()
org.apache.juneau.rest
@RestResourceannotation can now be applied to any class! You're no longer restricted to subclassing your resources fromRestServlet.
This is a major enhancement in the API. Anything you could do by subclassing fromRestServletshould have an equivalent for non-RestServletclasses.
The only restriction is that the top-level resource must subclass fromRestServlet. Child resources do not.
The majority of code has been split up into two separate classes:RestConfigServletConfig.RestContext- A read-only configuration that's the result of a snapshot of the config.
TheRestServletclass now has the following initialization method that allows you to override the config settings define via annotations:RestServlet.init(RestConfig)
RestServletclasses must have one of the following to allow it to be instantiated:- A
public T(RestConfig) - A
public T() - The parent resource must have a customized
RestResourceResolverfor instantiating it.
Non-RestServletclasses can optionally include the following init methods to gain access to the config and context:public init(RestConfig)public init(RestContext)
- New annotations added to
@RestResourceto allow non-RestServletresources to do the same as subclassing directly fromRestServlet:resourceResolver()- Specify aRestResourceResolverclass for resolving child resources.callHandler()- Specify aRestCallHandlerclass for handling the lifecycle of a REST call.infoProvider()- Specify aRestInfoProviderclass for customizing title/description/Swagger information on a REST resource.logger()- Specify aRestLoggerclass for handling logging.
- New annotations added to
@RestResourceand@RestMethodto simplify defining page title, text, and links on HTML views:@RestResource.pageTitle()@RestMethod.pageTitle()@RestResource.pageText()@RestMethod.pageText()@RestResource.pageLinks()@RestMethod.pageLinks()
// Old method @RestResource ( properties={@Property (name=HTMLDOC_title , value="System properties resource" ),@Property (name=HTMLDOC_description , value="REST interface for performing CRUD operations on system properties." ),@Property (name=HTMLDOC_navlinks , value="{up:'$R{requestParentURI}',options:'?method=OPTIONS'}" ) } )// New method @RestResource ( pageTitle="System properties resource" , pageDescription="REST interface for performing CRUD operations on system properties." , pageLinks="{up:'$R{requestParentURI}',options:'?method=OPTIONS'}" )Typically you're going to simply want to use the
titleanddescriptionannotations which apply to both the page title/text and the swagger doc:@RestResource ( title="System properties resource" , description="REST interface for performing CRUD operations on system properties." , pageLinks="{up:'$R{requestParentURI}',options:'?method=OPTIONS'}" ) RestResource.stylesheet()StreamResourcecan now contain multiple sources from a variety of source types (e.g.byte []InputStreams,Files, etc...) and is now immutable. It also includes a newStreamResourceBuilderclass.- Simplified remoteable proxies using the
@RestMethod (name="PROXY" )RemoteableServlet.
See// Server side @RestMethod (name="PROXY" , path="/myproxy/*" )public IAddressBook getProxy() {return addressBook ; }// Client side RestClient client = RestClient.create ().rootUrl(samplesUrl ).build(); IAddressBook ab = client.getRemoteableProxy(IAddressBook.class ,"/addressBook/myproxy" );@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.- You can now use numeric values in path annotations.
When using numeric variable names, you don't need to specify the variable name in the@Path annoation:@RestMethod (name="GET" , path="/myurl/{0}/{1}/{2}/*" )public void doGet(RestRequest req, RestResponse res,@Path String foo,@Path int bar,@Path UUID baz) { ... } @RestMethod.name()annotation is now optional. Defaults to"GET" .
org.apache.juneau.rest.client
- Revamped the client API to use builders.
- New doc:
1.5 - Debugging - The
RestClientclassdoX(Object url)methods now handle HttpClientURIBuilderinstances. - New methods added/updated to
RestClient:getRemoteableProxy(Class,Object)- For interface proxies defined using@RestMethod (name="PROXY" )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 ofNameValuePairsfor easy form posts.
This extends to all methods that take in the input.
- New methods on
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)
- New methods added to
RestClientBuilder:executorService(ExecutorService,boolean)paramFormat(ExecutorService,boolean)RestClientBuilder.plainTextParams()noTrace()- Adds aNo-Trace: trueheader on all requests to prevent the servlet from logging errors.
Useful for testing scenarios when you don't want the console to end up showing errors done on purpose.debug()now adds aDebug: trueheader on all requests.
- New methods added/updated to
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 ofNameValuePairs.getResponse(Class)- Can now pass in any of the following:HttpResponse- Returns the rawHttpResponsereturned by the innerHttpClient.Reader- Returns access to the raw reader of the response.InputStream- Returns access to the raw input stream of the response.
- New methods added to
NameValuePairs:append(String,Object)append(String,Object,PartSerializer)
RetryOnis now an abstract class with an additional method:
org.apache.juneau.microservice
"REST/port" configuration setting can now be a comma-limited list of port numbers to try.
You can also specify one or more0s to try a random port.- Methods added to
RestMicroserviceclass:RestMicroservice.getPort()RestMicroservice.getURI()- Override methods added from
Microserviceclass for easier method chaining.
6.1.0 (Feb 25, 2017)
Juneau 6.1.0 is a major update.
In particular, this release cleans up the BeanContext API to match
the PropertyStore/Context/Session paradigm
previously used in the serializer and parser APIs.
It also makes several improvements to the HTML and XML serialization support and introduces HTML5 DTO beans.
org.apache.juneau
- Improvements to XML serialization support.
- New supported XML formats:
XmlFormat.ATTRSformat can now be applied to bean classes to have all bean properties serialized as attributes instead of elements by default.XmlFormat.ELEMENTformat can now be applied to bean properties to override theXmlFormat.ATTRSsetting above on specific bean properties.- New
XmlFormat.ELEMENTSformat can be applied to a bean property of type array/Collection to represent the child elements. - New
XmlFormat.MIXEDformat can be applied to a bean property of type array/Collection to represent mixed content (text + child elements). - New
XmlFormat.MIXED_PWSformat. Identical toMIXED except preserves whitespace. - New
XmlFormat.TEXTformat can be applied to a bean property of a single object to represent a text node as a child. - New
XmlFormat.TEXT_PWSformat. Identical toTEXT except preserves whitespace. - New
XmlFormat.XMLTEXTformat that's identical toXmlFormat.TEXTexcept XML content is not escaped and serialized directly as the child content. The parser will reconvert this to the original XML text during parsing.
- New support methodology and other improvements to org.apache.juneau.xml documentation.
- Eliminated unnecessary
<string> elements. - Eliminated
XmlContentHandler - Parser efficiency improvements through reuse of string builders.
- Reworked and simplified the default XML serializers. The
XmlSerializer.DEFAULTserializer now has namespaces disabled, andXmlSerializer.DEFAULT_NShas namespaces enabled. The 'XML-JSON' serializers have been eliminated. - Eliminated the
addJsonTypeAttrsandaddJsonStringTypeAttrssettings. - Namespace support is now disabled by default.
- New supported XML formats:
- Significant modifications and improvements to HTML serialization support.
- Parser converted from
XMLEventReader-based toXMLStreamReader. - Eliminated many unnecessary type tags and
<string> elements and improved the readable layout. The new format is much leaner. - New exhaustive support methodology section added to org.apache.juneau.html documentation.
- Parser converted from
- New HTML5 DTO support: org.apache.juneau.dto.html5.
BeanContextclass split into separateBeanContextandBeanSessionclasses.- Session object meant to be single-use that can be discarded after use and contains session-level object cache and overridable Locale and TimeZone.
SerializerContextParserContextBeanContext.SerializerSessionandParserSessionnow extend directly fromBeanSession.- New settings in
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.
- Improvements to Parser class:
- Simplified the parse methods (e.g.
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.
ClassMetaobject.
For example:// Old way: ClassMeta<?> cm = parser.getMapClassMeta( HashMap.class , String.class , parser.getCollectionClassMeta( LinkedList.class , MyBean.class ) ); Map<String,List<MyBean>> map = (Map<String,List<MyBean>>)parser.parse(input, cm);// New way: Map<String,List<MyBean>> map = parser.parse(input, HashMap.class , String.class , LinkedList.class , MyBean.class ); - Arbitrarily-complex parameterized maps and collections can now be parsed without the need for creating intermediate
ClassMetaobjects. - No need for casting anymore if you were using the old
parseMap()andparseCollection()methods! - Changes allow me to eliminate
BeanContext.normalizeClassMeta()method. - Convenience methods added for setting parser properties:
// Old way: new JsonParser().setProperty(PARSER_strict ,true ).setProperty(BEAN_locale , mylocale);// New way: new JsonParser().setStrict(true ).setLocale(mylocale);
- Simplified the parse methods (e.g.
- Improvements to Serializer class:
- Convenience methods added for setting serializer properties:
// Old way: new JsonSerializer().setProperty(JSON_simpleMode ,true ).setProperty(SERIALIZER_quoteChar ,'"' );// New way: new JsonSerializer().setSimpleMode(true ).setQuoteChar('"' );
- Convenience methods added for setting serializer properties:
- Simplified
PojoSwapclass. Now just two methods: - General code improvements made to
ClassMetaclass.- All fields are now final which should improve overall performance.
- Replaced support for
toObjectMap()andfromObjectMap()/T(ObjectMap)methods with generalizedswap(BeanSession)/unswap(BeanSession,X)/T(BeanSession,X)methods.
See new sectionSwap methods
- Session-level media type now available through
BeanSession.getMediaType()method. Allows for swaps and serializer/parser behavior to be tailored to individual media types. - Several new
CalendarandDateswaps:CalendarSwap.ToString,DateSwap.ToString- ToStringsusing theDate.toString()method.CalendarSwap.ISO8601DT,DateSwap.ISO8601DT- To ISO8601 date-time strings.CalendarSwap.ISO8601DTZ,DateSwap.ISO8601DTZ- Same asISO8601DT , except always serializes in GMT.CalendarSwap.ISO8601DTP,DateSwap.ISO8601DTP- Same asISO8601DT except with millisecond precision.CalendarSwap.ISO8601DTPZ,DateSwap.ISO8601DTPZ- Same asISO8601DTZ except with millisecond precision.CalendarSwap.RFC2822DT,DateSwap.RFC2822DT- To RFC2822 date-time strings.CalendarSwap.RFC2822DTZ,DateSwap.RFC2822DTZ- Same asRFC2822DT , except always serializes in GMT.CalendarSwap.RFC2822D,DateSwap.RFC2822D- To RFC2822 date strings.CalendarSwap.DateTimeSimple,DateSwap.DateTimeSimple- To simple"yyyy/MM/dd HH:mm:ss" date-time strings.CalendarSwap.DateSimple,DateSwap.DateSimple- To simple"yyyy/MM/dd" date strings.CalendarSwap.TimeSimple,DateSwap.TimeSimple- To simple"HH:mm:ss" time strings.CalendarSwap.DateFull,DateSwap.DateFull- ToDateFormat.FULLdate strings.CalendarSwap.DateLong,DateSwap.DateLong- ToDateFormat.LONGdate strings.CalendarSwap.DateMedium,DateSwap.DateMedium- ToDateFormat.MEDIUMdate strings.CalendarSwap.DateShort,DateSwap.DateShort- ToDateFormat.SHORTdate strings.CalendarSwap.TimeFull,DateSwap.TimeFull- ToDateFormat.FULLtime strings.CalendarSwap.TimeLong,DateSwap.TimeLong- ToDateFormat.LONGtime strings.CalendarSwap.TimeMedium,DateSwap.TimeMedium- ToDateFormat.MEDIUMtime strings.CalendarSwap.TimeShort,DateSwap.TimeShort- ToDateFormat.SHORTtime strings.CalendarSwap.DateTimeFull,DateSwap.DateTimeFull- ToDateFormat.FULLdate-time strings.CalendarSwap.DateTimeLong,DateSwap.DateTimeLong- ToDateFormat.LONGdate-time strings.CalendarSwap.DateTimeMedium,DateSwap.DateTimeMedium- ToDateFormat.MEDIUMdate-time strings.CalendarSwap.DateTimeShort,DateSwap.DateTimeShort- ToDateFormat.SHORTdate-time strings.
- New method
SerializerGroup.getSerializerMatch(String)that returns the matched serializer and media type. - New method
ParserGroup.getParserMatch(String)that returns the matched parser and media type. - New method
EncoderGroup.getEncoderMatch(String)that returns the matched encoder and encoding. - General improvements to Bean Dictionary support.
- New
BeanDictionaryListclass can be used for defining reusable sets of bean dictionaries consisting of classes annotated with@Bean.typeName(). - New
BeanDictionaryMapclass can be used for defining reusable sets of bean dictionaries consisting of classes not annotated with@Bean.typeName(). - New
@Bean.beanDictionary()annotation.
- New
- Removed restriction on getters and setters to be prefixed with "getX/setX/isX" if a
@BeanProperty.name()annotation is used. - Improvements to ATOM DTO:
- New
AtomBuilderclass. - New setter method names for a better fluent design.
- Updated org.apache.juneau.dto.atom documentation.
- New
- New
MapSwapandStringSwapclasses. - New
WriterSerializer.println(Object)method. Useful for debugging purposes. - New
BeanContext.getClassMeta(Type,Type...)andBeanSession.getClassMeta(Type,Type...)methods for retrieving Map and Collection class metas. Replaces the variousgetMapClassMeta()/getCollectionClassMeta()methods. - New section added to this document:
Juneau Data Transfer Objects (org.apache.juneau.dto) - Modified the UON specification to work with mixed content.
- The new specification is considerably cleaner and eliminates the need for separate normal/simple modes.
It also allows for arbitrary whitespace to be added to the output without any confusion. - Eliminated the
UonParser.andDEFAULT_WS_AWARE UrlEncodingParser.parsers.DEFAULT_WS_AWARE
The normalUonParser.DEFAULTandUrlEncodingParser.DEFAULTparsers will now handle whitespace. - Eliminated the
UonParserContext.configuration setting.UON_whitespaceAware - Eliminated the
UonSerializer.,DEFAULT_SIMPLE UonSerializer.andDEFAULT_SIMPLE_ENCODING UrlEncodingSerializer.serializers since there is no separate simple mode anymore.DEFAULT_SIMPLE - Eliminated the
UonParserContext.configuration setting.UON_simpleMode
- The new specification is considerably cleaner and eliminates the need for separate normal/simple modes.
- Added new
OutputStreamSerializer.serializeToHex(Object)method.
Useful mostly for testing purposes.
Equivalently, theParser.parse(Object,Class)method can now read the output from this method. - Eliminated the
@Bean (subTypeProperty)@Bean (subTypes)@Bean.beanDictionary()annotation on parent classes and interfaces.
This has the added benefit of simplifying the overall code. - The
SerializerContext.SERIALIZER_addBeanTypeProperties - Combined the
SERIALIZER_addIndentation/JSON_addWhitespace/UON_addWhitespaceproperties into a singleSerializerContext.SERIALIZER_useWhitespace
org.apache.juneau.rest
RestRequestnow passes locale and timezone to serializers/parsers/transforms.RestRequest.getTimeZone()- Standardized the following methods in
RestRequestto remove dependency onClassMetaobjects and eliminate the need for casts:RestRequest.getHeader(String,Class)RestRequest.getHeader(String,Object,Class)RestRequest.getHeader(String,Type,Type...)RestRequest.getQueryParameter(String,Class)RestRequest.getQueryParameter(String,Object,Class)RestRequest.getQueryParameter(String,Type,Type...)RestRequest.getQueryParameter(String,Object,Type,Type...)RestRequest.getQueryParameters(String,Class)RestRequest.getQueryParameters(String,Type,Type...)RestRequest.getFormDataParameter(String,Class)RestRequest.getFormDataParameter(String,Object,Class)RestRequest.getFormDataParameters(String,Class)RestRequest.getFormDataParameter(String,Type,Type...)RestRequest.getFormDataParameters(String,Type,Type...)RestRequest.getPathParameter(String,Class)RestRequest.getPathParameter(String,Type,Type...)RestRequest.getBody(Class)RestRequest.getBody(Type,Type...)
- New methods on
NameValuePairs - Fixed issue where whitespace was not added to UON/URL-Encoding output when
&plainText=truespecified.
6.0.1 (Jan 3, 2017)
Juneau 6.0.1 is a minor update.
org.apache.juneau
- General improvements to JSON parser.
- Several fixes to handle obscure edge cases.
- New properties in
ParserContextParserContext.PARSER_strictParserContext.PARSER_inputStreamCharsetParserContext.PARSER_fileCharset
- Removed
JsonParserContext.JSON_strictMode. Replaced byPARSER_strict. byte[] Parser.parse(Object,Class)for reader-based parsers.
6.0.0 (Oct 3, 2016)
Juneau 6.0.0 is a major update.
The major change is rebranding from "Juno" to "Juneau" in preparation for donation to the Apache Foundation.
org.apache.juneau
- Major changes around how serializer and parser class properties are defined to improve performance
and concurrency.
- New
PropertyStoreclass - Used for creating context objects. - New
Contextclass - Read-only configurations for serializers and parsers. - New
Sessionclass - One-time use objects used by serializers and parsers. - All context context properties can now also be specified via system properties.
- New
- Refactored serializer and parser APIs for more consistency between stream-based and character-based serializers
and parsers.
- More consistent handling of exceptions.
- More consistent method declarations.
- Refactored var resolver API and added them to a new package -
org.apache.juneau.svl.- Support for stream-based variables -
StreamedVar. - Added support for context and session objects.
- Support for stream-based variables -
- Eliminated
"_class" properties and replaced them with"_type" properties. The class properties were a little-used feature where we would serialize fully-qualified class names when the class type could not be inferred through reflection. It's been replaced with bean type names and bean dictionaries. Instead of class names, we serialize"_type" properties whose name is the type name defined on the bean being serialized. The parsers use a 'dictionary' of bean classes to resolve those names to actual bean classes. The following features were added to enable this support:@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"_type" .@BeanProperty.beanDictionary()- Define a type dictionary for a particular bean property value. This overrides the value specified usingBeanContext.BEAN_beanDictionary.SerializerContext.SERIALIZER_addBeanTypeProperties
@Bean.typeName()value replaces the@Xml.name()annotation, and the"type" and"_class" attributes in the XML and HTML serializers have been standardized on a single"_type" attribute. - Refactor bean filter support to use
BeanFilterBuilderclass. Allows theBeanFilterclass to use final fields. MessagePacksupport.- Serializers can now serialize directly to
Files. SeeSerializer.serialize(Object,Object) - Parsers can now parse directly from
Filesand other types. SeeParser.parse(Object,ClassMeta) - Parsers will automatically covert numeric input to POJOs that have numeric constructors (e.g.
java.util.Date). - Renamed 'Filters' to 'BeanFilters' and 'PojoSwaps'. Filters is just too overloaded a term.
- Internal utility classes moved to a new
org.apache.juneau.internalpackage. These internal utility classes are not meant for consumption outside the Juneau codebase. - New methods on
Parser:org.apache.juneau.parser.Parser.createSession(ObjectMap,Method,Object)Parser.getMediaRanges()
- New methods on
Serializer:org.apache.juneau.serializer.Serializer.createSession(ObjectMap,Method)Serializer.getMediaRanges()
- New
@Bean.sort()annotation. - Added
@Bean.properties annotations on various DTO beans to make the ordering consistent between IBM and Oracle JVMs.
IBM JVMs maintain the order of methods in a class, whereas Oracle JVMs do not. - Serializers and parsers now automatically convert
Classobjects to readable names viaClassUtils.getReadableClassName(Class). - Eliminated the
ClassFilterclass since it's no longer needed. - Code and concurrency improvements to
SerializerGroupandParserGroup. - Various enhancements to
BeanContext.convertToType(Object,Class) - New properties on
HtmlSerializer:HtmlSerializerContext.HTML_detectLinksInStringsHtmlSerializerContext.HTML_lookForLabelParameters&label=MyLabelto URL.HtmlSerializerContext.HTML_labelParameterHtmlSerializerContext.URI_ANCHORHtmlSerializerContext.HTML_uriAnchorText
- Removed generics from
BeanPropertyMeta. - Introduced new classes to eliminate the references to language-specific metadata in the core metadata classes:
- Renamed
@Transformannotation to@Pojo - Introduced
Swagger DTOs.
org.apache.juneau.rest
- OPTIONS pages replaced with Swagger documents.
Lots of changes related to supporting Swagger.
- Annotation name changes to conform to Swagger specs:
@Attr ->@Path ,@QParam ->@Query ,@Param ->@FormData ,@Content ->@Body - Eliminated
ResourceOptionsand related code. - New annotations and related methods:
@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()
- Annotation name changes to conform to Swagger specs:
- New
RestServletContext.paramFormat - New/updated methods on
RestServlet:RestServlet.createProperties()RestServlet.createBeanContext(ObjectMap,Class[],Class[])RestServlet.createBeanFilters()RestServlet.createPojoSwaps()RestServlet.createParsers(ObjectMap,Class[],Class[])RestServlet.createUrlEncodingSerializer(ObjectMap,Class[],Class[])RestServlet.createUrlEncodingParser(ObjectMap,Class[],Class[])RestServlet.createConverters(ObjectMap)RestServlet.createDefaultRequestHeaders(ObjectMap)RestServlet.createDefaultResponseHeaders(ObjectMap)RestServlet.createEncoders(ObjectMap)RestServlet.createGuards(ObjectMap)RestServlet.createMimetypesFileTypeMap(ObjectMap)RestServlet.createResponseHandlers(ObjectMap)
- New client-version annotations:
RestResource.clientVersionHeader()- The name of the header used to identify the client version.RestMethod.clientVersion()- The client version range applied to a Java method.
org.apache.juneau.rest.client
- Removed the
JazzRestClientclass. - New method
RestClient.setClientVersion(String)
5.2.0.1 (Mar 23, 2016)
Juno 5.2.0.1 is a moderate update.
com.ibm.team.juno
- Improved support for multi-line values in config files. Any line that begins with whitespace is interpreted as a continuation of the previous line.
- Support for
'\uXXXX' character sequences in config files. - Fixed issue in
XmlSerializerwhere'\r' and'\n' characters were not being handled per XML specs. - New methods on
ObjectList:ObjectList.getAt(Class,String)ObjectList.putAt(String,Object)ObjectList.postAt(String,Object)ObjectList.deleteAt(String)
- New methods on
ObjectMap:ObjectMap.getAt(Class,String)ObjectMap.putAt(String,Object)ObjectMap.postAt(String,Object)ObjectMap.deleteAt(String)
@ThreadSafe- New
ClassFilterclass. ConfigFile.getResolving(StringVarResolver,boolean)ConfigFile.getStringVar()- New
ParserContext.PARSER_trimStrings - New
SerializerContext.SERIALIZER_trimStrings Args.getStringVar()}- New
ManifestFileclass - New
MessageBundleclass. ReplacesSafeResourceBundle /SafeResourceMultiBundle /RestNls . - New
StringMapVar - New
StringVarsStringVar - New
JuneauLoggerclass. - Default value for
XmlParserContext.XML_trimWhitespacetrue .
Server
- New methods on
RestContext:
Client
- Fixed potential issue in
RestClientwhere the HTTP connection pool could end up exhausted if an error occurred. - Improved thread safety on
RestClient. - New warning message is logged if a
RestClientis garbage collected without being closed:"WARNING: RestClient garbage collected before it was finalized."
5.2.0.0 (Dec 30, 2015)
Juno 5.2.0.0 is a major update. Major changes have been made to the microservice architecture and config INI file APIs.
Core
- Significant changes and enhancements to the
org.apache.juneau.configAPI.- More consistent handling of comma-delimited lists of objects.
- New methods in
ConfigFileConfigFile.getStringArray(String)ConfigFile.getStringArray(String,String[])ConfigFile.getSectionAsBean(String,Class)ConfigFile.writeProperties(String,Object,boolean,Class[])ConfigFile.getSectionMap(String)ConfigFile.containsNonEmptyValue(String)ConfigFile.isEncoded(String)ConfigFile.addListener(ConfigFileListener)ConfigFile.merge(ConfigFile)ConfigFile.getResolving()ConfigFile.getResolving(StringVarResolver)ConfigFile.toWritable()Writableinterface 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)"M" and"K" to identify millions and thousands.
- New methods in
ConfigMgrConfigMgr.create()ConfigMgr.create(Reader)ConfigMgr.create(File)ConfigMgr.deleteAll()
- New methods in
SectionSection.setParent(ConfigFileImpl)Section.setName(String)
- New interfaces:
org.apache.juneau.config.ConfigFileListenerorg.apache.juneau.config.SectionListenerorg.apache.juneau.config.EntryListener
org.apache.juneau.config.Encoder- The name of the default section is now
"default" . Before it was justnull . org.apache.juneau.config.XorEncoder"org.apache.juneau.config.XorEncoder.key" system property.
- Support for converting Strings to POJOs if the POJO class has any of the following static methods:
fromString(String)valueOf(String)(e.g. enums)parse(String)(e.g. loggingLevelclass)parseString(String)forName(String)(e.g.ClassandCharsetclasses)
- Support for parsing into objects with unbound type variables.
For example, if you have a class
Pair<S,T>and you try to parse into this class (e.g.parser.parse(in, Pair.), the unbound type variables is interpreted asclass )Objectinstead of throwing an exception. - Support for serializing/parsing the following new types:
AtomicIntegerAtomicLongBigIntegerBigDecimal
- Parsers have been enhanced to allow parent POJOs and field names to be passed into child POJOs.
New
@NamePropertyand@ParentPropertyannotations are provided for identifying methods for setting names and parent POJOs on child POJOs. For example, the config fileSectionConfigFile - New classes and interfaces:
Streamableinterface for identifying objects that can be serialized directly to an output stream.Writableinterface for identifying objects that can be serialized directly to a writer.StringObjectByteArrayCacheByteArrayInOutStreamFileUtilsThrowableUtilsStringVarMultipartStringVarWithDefault
- New fields on
ObjectList: - New fields and methods on
ObjectMap: - New methods in
ArrayUtils: - New methods in
IOUtils: - New methods on
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)
- New methods on
ProcBuilder: - New methods on
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[])
- New
StringVar.doResolve(String) - New
StringVarResolver.DEFAULT - Eliminated dependency on
javax.mail.internet.MimeUtilityby implementing our ownStringUtils.base64Encode(byte[])method. CalendarSwapandDateSwapclasses now handle blank input better. Returnsnull instead of throwing an exception.HtmlDocSerializerspecifies the default CSS location as/servletPath/style.cssinstead of/servletPath/htdocs/juneau.css. This coincides with enhancements made in the server code for specifying styles.HtmlDocSerializerwraps 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.- Fixed indentation inconsistencies in
HtmlDocSerializer. - Renamed
HtmlSchemaSerializertoHtmlSchemaDocSerializer. - RDF serializers and parsers now support
RdfProperties.RDF_looseCollectionloose collections. - RDF parser handles case where resources point to themselves (an unfortunate behavior in JFS RDF documents).
- JSON parser with throw an exception in strict mode if it encounters numbers that are valid in Java but invalid in JSON (e.g. octal, hexadecimal numbers).
Parsermethods now check fornull input.SerializerGroupandParserGroupignores serializers and parsers if they throwNoClassDefFoundErrors.UrlEncodingParsercreates lists if the same attribute name is encountered more than once. Before it would just replace the previous value with the new value.- New
UrlEncodingSerializer.DEFAULT_SIMPLE_EXPANDED - Changes to
Args:getMainArg(int)changed toArgs.getArg(int). Non-existent arguments are returned asnull instead of blank strings. This is more inline with the behavior of the rest of the library.- New
Args.hasArg(int)method.
- Removed
org.apache.juneau.utils.CharsetUtilsclass. - Removed
org.apache.juneau.utils.ConcurrentIdentityListclass. - Fixed bug in
MultiIterableclass. PojoIntrospectormust now be instantiated with aReaderParser. Simplifies the API on the class.PojoRestmust now be instantiated with aReaderParser. Simplifies the API on the class.MessageBundleandSafeResourceMultiBundlemoved from server component.- Several bug fixes and performance improvements in
StringVarResolver - Various enhancements to
TeeWriterandTeeOutputStream. - Renamed
CharSettoAsciiSet. SerializerGroupandParserGroupnow ignoresNoClassDefFoundErrorsso that resources that include Jena support can continue to operate even if the Jena libraries are not present.- New
FileUtils.createTempFile(String)method. - New
PojoQuerymodified to handle bean getters that throw exceptions.
Client
- Upgraded to use Apache HttpClient 4.5.
- New classes:
- Removed
org.apache.juneau.rest.client.LaxRedirectStrategy. Use HTTP Client equivalent. - New methods on
RestCall: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 fromexecute().RestCall.getCapturedResponse()RestCall.getResponsePojoRest(Class)RestCall.getResponsePojoRest()RestCall.logTo(Level,Logger)RestCall.setConfig(RequestConfig)
- New lifecycle listener methods on
RestCallInterceptor: - New methods on
RestClient:RestClient.setBasicAuth(String,int,String,String)RestClient.logTo(Level,Logger)RestClient.setRootUrl(String)RestClient.enableSSL(SSLOpts)RestClient.enableLaxSSL()RestClient.doCall(HttpMethod,Object,Object)RestClient.createHttpClientBuilder()
- New passthrough methods on
RestClientdefined onHttpClientBuilder: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)
JazzRestClientnow supports OIDC authentication.- These classes are now deprecated and will be removed in a future release:
org.apache.juneau.rest.client.jazz.CertificateStoreorg.apache.juneau.rest.client.jazz.ICertificateValidatororg.apache.juneau.rest.client.jazz.ITrustStoreProviderorg.apache.juneau.rest.client.jazz.LenientCertificateValidatororg.apache.juneau.rest.client.jazz.SharedTrustStoreProviderorg.apache.juneau.rest.client.jazz.ValidatingX509TrustManager
Server
- New
ReaderResourceclass. Represents the contents of a text file with convenience methods for resolvingStringVarReaderscontaining text withStringVarResolver - New
StreamResourceclass. REST Java methods can return instances of these to serializeOutputStreams. - Fixed a bug in the stack trace hash algorithm in
RestException. - New methods in
RestRequest:RestRequest.getReaderResource(String)getVarResource(String).RestRequest.getReaderResource(String,boolean)RestRequest.getReaderResource(String,boolean,String)
- Changes in
RestResponse:- Don't set
Content-Encoding: identitywhen no encoding is used. Some clients don't interpret it correctly.
- Don't set
- New methods in
RestServlet:RestServlet.getChildClasses()@RestResource.children()annotation.RestServlet.shouldLog(HttpServletRequest,HttpServletResponse,RestException)RestServlet.shouldLogStackTrace(HttpServletRequest,HttpServletResponse,RestException)RestServlet.logObjects(Level,String,Object[])RestServlet.resolveStaticFile(String)RestServlet.createStyleSheet()RestServlet.createFavIcon()RestServlet.createStaticFilesMap()RestServlet.getConfigMgr()
- Removed
JsoParserfromBasicRestServletandRestServletJenaDefault - Removed
RestServletProperties.REST_htDocsFolder. Replaced with@RestResource.staticFiles(). - New annotations on
@RestResource.RestResource.stylesheet()RestResource.favicon()@RestResource.staticFiles()
- Eliminated
org.apache.juneau.rest.jaxrs.JsonProviderclass. Some JAX-RS implementations use code scanning to find providers, so if you were usingDefaultJenaProvider, it would pick upJsonProvideras well. It's easy enough to create your own implementation if needed. - OPTIONS pages now specify
consumesandproducesfields instead ofacceptandcontentTypewhich was confusing. - Eliminated
propertiesfrom OPTIONS pages. - New
ResourceLink.ResourceLink(String,RestRequest,String,Object[]) - New response handlers:
StreamableHandler- Allows REST Java methods to return instances ofStreamable.WritableHandler- Allows REST Java methods to return instances ofWritable.
- New DevOps stylesheet.
- Servlet initialization and HTTP requests are now logged at
FINE level. - Added
abstract modifier on variousRestServlet subclasses to indicate that they're meant to be subclassed. - New
RestUtils.trimPathInfo(StringBuffer,String,String)method.
Microservice
- Completely revamped API.
- New
Microserviceclass that serves as a generic interface for microservices and their lifecycles. - New
RestMicroserviceclass that implements a microservice consisting of a REST interface.- REST resources and configuration settings can be defined through either manifest files or config files.
- Enhanced logging support.
- Easy-to-configure SSL support.
- BASIC auth support.
- Automatic restartability if the config file changes.
- Eliminated
org.apache.juneau.microservice.Mainclass. This is replaced by the microservice classes defined above. ResourceResourceGroup"$A{key,default}"" - Command line arguments."$MF{key,default}"" - Manifest file entries.
- CSS stylesheet now configurable through config file entry
"REST/stylesheet" . - New
BasicRestServletJenaclass if you want your REST interface to support RDF. - Eliminated the following classes:
org.apache.juneau.microservice.RootResourceorg.apache.juneau.microservice.SampleResource
- New predefined reusable resources:
ConfigResource- REST resource for viewing and editing microservice config file.LogsResource- REST resource for viewing log files.SampleRootResource- Sample REST resource that contains the config and logs resource as children.ShutdownResource- REST resource for stopping the microservice JVM. Useful for testing purposes.
Samples
- Converted to a REST microservice.
- Look-and-feel changed to IBM DevOps.
Documentation Updates
org.apache.juneau.microservice- New package-level javadoc.org.apache.juneau.config- New package-level javadoc.StringVarResolverorg.apache.juneau.rest.client- New package-level javadoc.Overview / Samplesorg.apache.juneau.transform / Stop Classes- New section.org.apache.juneau.rest- Extensive updates.
5.1.0.20 (Sept 5, 2015)
Juno 5.1.0.20 is a moderate update.
The biggest improvement is the ability to associate external INI config files with REST servlets using the ConfigFile
Core
- Significant API changes to
org.apache.juneau.configAPI.ConfigFile- New
ConfigMgr - Serializers and parsers can be associated with config files for storing and retrieving POJOs. Default support provided for JSON.
- New
SimpleHtmlWriterclass. Can be used for simple HTML DOM construction. - New
ProcBuilderclass for calling external processes. - New
ObjectMap.remove(Class,String,Object) "class='link'" added to links generated byHtmlDocSerializer.- New
EncoderGroup#append(EncoderGroup) - New
HtmlDocSerializerContext.HTMLDOC_addLinksconfiguration property. - Modified the
Parser.createContext(ObjectMap,Method,Object)method. Outer context objects can be passed in to create instances of non-static inner classes. - Fixed bug in
HtmlStrippedDocSerializerwhere exception was thrown when trying to serialize primitive arrays. JsonParsernow handles parsing JSON boolean/numeric values as strings to bean properties of type boolean or number.UrlEncodingSerializerandUrlEncodingParsernow represent arrays and collections as key-value pairs where the keys are numbers (e.g."?0=foo&1=bar" ).- Various internal improvements to
IOPipe. - New
ReflectionUtils.getResource(Class,String)method. StringUtils.parseNumber(String,Class)now returns zero for empty strings. This affects the way most parsers handle blank values.
Server
- You can now parse into non-static inner classes of a servlet for parameters/attributes/content. Useful if you like to define your marshaller beans inside your servlet.
- Changes to
RestServlet:- New methods for accessing external INI config files:
RestServlet.getConfig()
RestServlet.createConfigFile() - New
"$C{...}" variable that resolve to INI config file values. - New
"$UE{...}" variable that URL-encodes the value inside the variable. - New convenience methods for retrieving classpath resource files:
RestServlet.getResource(String)
RestServlet.getResourceAsString(String)
RestServlet.getResource(Class,String,String) - New
RestServlet.handleNotFound(int,RestRequest,RestResponse)
- New methods for accessing external INI config files:
BasicRestServletnow automatically processes"/favicon.ico" requests by overriding the newRestServlet.handleNotFound(int,RestRequest,RestResponse)- New
RestRequestmethods:RestRequest.resolveVars(String)RestRequest.getVarResource(String)RestRequest.getConfig()
- New
RestResponsemethods:RestResponse.getDirectWriter(String).RestResponse.getNegotiatedWriter().getWriter()now returns an unnegotiated writer.getUnbufferedWriter()has been removed.
- New
@RestMethod.encoders()andRestMethod.inheritEncoders() - New
@RestResource.config()annotation for associating externalConfigFile ResourceLink- New
org.apache.juneau.rest.matcherspackage for commonly-usedRestMatchers:
Microservice
- New juneau-microservice.jar file that encapsulates all 3 juneau jars with code necessary for creating fast and efficent jetty-powered REST microservices.
Contains the following:- Jetty 8.0
- Apache HttpClient 4.3.5
- Apache Commons FileUpload 1.3.1
- Microservice now supports Java 6 (previously required Java 7)
5.1.0.19 (Aug 15, 2015)
Juno 5.1.0.19 is a minor update in terms of core functionality.
But it introduces a Microservices
Core
- Beans can now be serialized to and parsed from
ObjectMaps. SeeSerializing to ObjectMapsfor details. - New
ObjectMap.include(String[])andObjectMap.exclude(String[])methods. @Htmlannotations can now be applied to bean properties.- New
IOPipeutility class. - Behavior change on
StringVarResolvernull input now results in blank strings instead ofnull .
Client
- New
RestClient.doCallback(String)method.
Server
- New
RestRequest.getHeaders()method. - New
RestResponse.getUnbufferedWriter()method. - Fixed bug that was preventing
x-response-headersparameter from working correctly. - Added
@Bean.propertiesannotations to the various classes inorg.apache.juneau.rest.labelsso that the order of the bean properties are consistent on all JVMs. On IBM JVMs this is unnecessary because the order of the properties as defined in the class are stored in the bytecode. Other JVMs such as OpenJRE do not implement this feature causing the bean properties to be in random order. - New
ResourceDescription.ResourceDescription(RestRequest,String,String)
5.1.0.18 (Aug 5, 2015)
Juno 5.1.0.18 is a minor update affecting the server component only.
Server
- Fixed bug where localized strings weren't resolving when using chained resource bundles.
- Servlet and method labels and descriptions can now contain embedded string variables.
- New
RestMethod.input()RestMethod.responses()descriptionannotations added 2 days ago with a simpler design. - New methods on
RestServlet:RestServlet.getMethodDescription(String,RestRequest)RestServlet.createRequestVarResolver(RestRequest)RestServlet.resolveChild(Class)RestServlet.replaceChild(RestServlet)
- Reverted the
MethodDescription
5.1.0.17 (Aug 3, 2015)
Juno 5.1.0.17 is a major update.
Core
BeanMap.get(Object)andBeanMap.put(String,Object)now automatically performs filtering if filters are defined on the bean property or bean property class.- Deleted the following methods which are now unnecessary:
BeanMap.getFiltered(String)BeanMap.putFiltered(String,Object)BeanMapEntry.getFiltered(String)BeanMapEntry.putFiltered(String,Object)BeanMapEntry.putFiltered(String,Object)BeanPropertyMeta.getFiltered()BeanPropertyMeta.setFiltered(Object)BeanPropertyMeta.getTransformedClassMeta()
BeanPropertyMeta.getClassMeta()now returns the filtered type of the property.
- Deleted the following methods which are now unnecessary:
StringVarResolverStringVarResolver- Fixed bug where inner interface classes being used in
RestResource.filters()were being interpreted as surrogate classes because they have hidden 1-arg constructors due to being inner classes. - Fixed bug in
MultiSetwhere exception was being thrown if last set was empty. - New
ZipFileListclass for providing efficiently zipped directories through the REST interface. - New
RdfProperties.RDF_useXmlNamespacesproperty. - New
XmlParserContext.XML_preserveRootElement - Worked around bug in Sun VM on OS/X where XML parser was throwing an exception when trying to set a reporter.
Server
- New
ZipFileListResponseHandlerclass. - Simplified labels in servlet resource bundles:
"[ClassName].ResourceDescription"is now"[ClassName].label"."[ClassName].MethodDescription.[methodName]"is now"[ClassName].[methodName]".
- Several changes to
RestRequest:- Added new methods:
RestRequest.getQueryParameterMap()RestRequest.getQueryParameterNames()RestRequest.getPathInfoUndecoded()RestRequest.getPathRemainderUndecoded()RestRequest.getTrimmedRequestURI()RestRequest.getTrimmedRequestURL()RestRequest.getServletTitle()RestRequest.getServletDescription()RestRequest.getMethodDescription()
- Behavior changes to
HttpServletRequestWrapper.getPathInfo()to follow Servlet specs. Returnsnull instead of blank for no path info. RestRequest.getPathRemainder()RestRequest.getPathRemainderUndecoded()- Bug fixes in
RestRequest.getRequestParentURI()"/*" . - Bug fixes in
RestRequest.getServletURI()"/*" .
- Added new methods:
- New string replacement variables:
$R{contextPath}- Returns value fromRestRequest.getContextPath()$R{methodDescription}- Returns value fromRestRequest.getMethodDescription()$R{resourceTitle}- Returns value fromRestRequest.getServletTitle()$R{resourceDescription}- Returns value fromRestRequest.getServletDescription()$R{trimmedRequestURI}- Returns value fromRestRequest.getTrimmedRequestURI()$E{var}- Environment variables.
- Added methods
RestServlet.getDescription(RestRequest)RestServlet.getLabel(RestRequest) BasicRestServletandRestServletJenaDefault@Property (name=HTMLDOC_title , value="$R{resourceTitle}" ),@Property (name=HTMLDOC_description , value="$R{resourceDescription}" )- Options pages on
BasicRestServletandRestServletJenaDefault@Property (name=HTMLDOC_navlinks , value="{back:'$R{servletURI}" ),@Property (name=HTMLDOC_description , value="Resource options" ) - New
BasicRestServletGroupclass. - Removed
RestServletProperties.REST_trimTrailingUriSlashesandRestServletProperties.REST_pathInfoBlankForNull. - New annotations for providing labels and descriptions. Useful if you don't plan on having to support other languages, so you don't
want to provide labels in resource bundles.
RestResource.label()@RestResource.description()@RestMethod.description()RestMethod#responses()Attr.description()Content.description()HasParam.description()HasQParam.description()Header.description()Param.description()QParam.description()
- Support for sorting resources by name in
ChildResourceDescriptions.
Samples
- Added
/tempDir/uploadshowing how to useServletFileUploadwith multipart form posts.
5.1.0.16 (June 28, 2015)
Juno 5.1.0.16 is a moderate update.
Core
- New methods on
ClassMetathat eliminates language-specific code in the general class metadata.ClassMeta.getXmlMeta()ClassMeta.getJsonMeta()ClassMeta.getHtmlMeta()ClassMeta.getUrlEncodingMeta()ClassMeta.getRdfMeta()
- New
JsonType.ANYenum. - New
@Html.asPlainText()annotation. - New
HtmlDocSerializerContext.HTMLDOC_cssImports - Significant changes to RDF support.
- New
@Rdfand@RdfSchemaannotations. These replace the use of defining namespaced through the XML annotations, and allows XML and RDF to be serialized using different namespaces. - Support for serializing arrays/collections as RDF bags, RDF lists, and multi-valued properties.
- Fixed warning message about
"tab" setting when using the N3/Turtle serializers.
- New
- New
SerializerContext.SERIALIZER_sortCollectionsSerializerContext.SERIALIZER_sortMaps - FindBug fixes.
Server
- New
RestRequest.getServletParentURI() - New
$R{servletParentURI}variable. - Removed final modifier from
ChildResourceDescriptions.
Samples
- Added source code links to examples.
5.1.0.15 (May 24, 2015)
Juno 5.1.0.15 is a minor update.
Core
- New properties in
SerializerContextSerializerContext.SERIALIZER_relativeUriBaseSerializerContext.SERIALIZER_absolutePathUriBase
SERIALIZER_uriAuthorityandSERIALIZER_uriContextproperties. - Improvements in
CsvSerializer.
Server
- New properties in
RestServletProperties:REST_defaultCharsetREST_servletURIREST_relativeServletURI
- Improvements involving path calculations when servlets deployed outside of a war file with a context root.
Client
- New methods in
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...)
5.1.0.14 (May 10, 2015)
Juno 5.1.0.14 is a moderate update.
The major addition is support for Remoteable Services, the ability
to invoke server-side POJO methods through client-side proxy interfaces.
Core
- Simplified
PojoIntrospectorclass. - New
ClassUtils.getMethodSignature(Method)method.
Client
- New methods in
RestClientfor working with remoteable services:RestClient.setRemoteableServletUri(String)RestClient.getRemoteableProxy(Class)
Server
- Added a default OPTIONS page to
BasicRestServletandRestServletJenaDefault RestServletProperties.REST_allowMethodParamhas been enhanced to allow you to explicitly specify which HTTP methods can be used in the&methodparameter.- New methods added to
RestRequest:RestRequest.getParser()RestRequest.getReaderParser()
5.1.0.13 (Apr 24, 2015)
Juno 5.1.0.13 is a minor update.
Core
ClassMeta.newInstance()method can now create new instances of arrays.- Arguments passed to
LinkUrlEncodingSerializer, so arbitrary POJOs can now be passed as arguments. - New date filters:
org.apache.juneau.transforms.Datefilter.ISO8601DTZPandorg.apache.juneau.transforms.Datefilter.SimpleP. - New
HtmlDocSerializerContext.HTMLDOC_nowrapHtmlDocSerializerclass. Adds"* {white-space:nowrap}" to the style header to prevent word wrapping. - Fixed bug in
UonParserwhere passing in a blank value on an array or collection type in a form post would cause aClassCastException. New behavior creates an empty array orCollection. - Improved implementation of
UrlEncodingSerializer.serializeUrlPart(Object)
Server
RestConverterAPI fixed to handle the existence of POJO filters.Introspectable/Queryable/Traversableclasses can now work with filtered POJOs.@RestResource.messages()annotation can now be defined on super and subclasses so that NLS messages can be defined in multiple resource bundles.- Performance improvements in
RestServletNlsclass. - Fixed bug where two REST java methods mapped to the same path pattern wasn't triggering an exception when it was supposed to.
Client
- New
RestCall.setRedirectMaxAttempts(int) - New
RestCall#setRetryable(int,long,RetryOn) - New
RestCallInterceptor.onRetry(RestCall,int,HttpRequest,HttpResponse)method for listening in on retry attempts.
5.1.0.12 (Mar 28, 2015)
Juno 5.1.0.12 is a minor update.
Core
- Fixed
ConfigFile.isEmpty() - Changed behavior on
UonParserto not treat'~' characters as escapes unless followed by one of the following characters:( ) , $ = ~.
Client
- New class
RestCallInterceptor. Allows responses to be inspected and modified before being processed. ReplacesRestClientListenerclass. - Minor connection cleanup fixes.
5.1.0.11 (Feb 14, 2015)
Juno 5.1.0.11 is a moderate update.
Core
- Additions to
@Htmlbean annotation.- New
@Html.noTables()annotation that prevents arrays/Collections from being serialized as tables. - New
@Html.noTableHeaders()annotation that prevents HTML tables from having header rows.
- New
- Several improvements to URL-Encoding support.
- Improved whitespace handling in
UonParser. - New
UonParserContext.UON_whitespaceAware - New
UrlEncodingContext.URLENC_expandedParams - New
@UrlEncoding.expandedParams()annotation that specifies that bean properties of type array/Collection be serialized as multi-part parameters (e.g.&key=val1&key=val2).
- Improved whitespace handling in
- New
JsonSerializerContext.JSON_escapeSolidus - New
TeeOutputStreamandTeeWriterclasses. - New
ClassMeta.isInstance(Object)method. - Performance improvements when using the
BeanMap.add(String,Object)method. Array properties are stored in a temporary list cache untilBeanMap.getBean()is called. - New
BeanPropertyMeta.add(BeanMap,Object) - Config INI files now support keys with name
"*" .
Server
- REST method parameters can now be generic types (e.g.
@Param ("foo" ) Map<String,Integer> foo - New
@Param.multipart()@Query.multipart() - GET parameters are now CASE-SENSITIVE per W3C standards.
&Contentmust now be specified as&content.&Methodmust now be specified as&method.&debugmust now be specified as&debug=true.&plainTextmust now be specified as&plainText=true.¬racemust now be specified as&noTrace=true.
- Performance improvements around query parameters.
- New methods on
RestRequestfor handling multi-part parameters:RestRequest.getParameters(String,Class)RestRequest#getQueryParameters(String,Class)
- Fixed Jetty issue in
RestResponse.setHeader(String,String)where setting theContent-Typethrough this method was inconsistent with the behavior in WAS/Tomcat. &noTrace=truenow prevents any errors from being logged in log file.- Workaround for Jetty issue where
ServletContext.getContextPath()always ends with"null" . RestServletProperties.REST_allowMethodParamis nowtrue by default on all subclasses ofBasicRestServletandRestServletJenaDefault
Client
- New method
RestCall.allowRedirectsOnPosts(boolean). - New method
RestCall.peekInputStream()allows you to read response bodies without interrupting execution flow. - New method
Session.toString()now useful for debugging purposes. Shows all request/response headers and bodies. RestCallExceptionnow includesHttpResponseobject for easier debugging.- New method
RestClient.addListener(RestClientListener)for registering request/response listeners. - New
RestClient.setClassLoader(ClassLoader) - TLS support in
JazzRestClient.
Other changes
samples.earandsamples.warprojects have been replaced with an OSGi bundle with activated servlets injuno.samples.
5.1.0.10 (Dec 23, 2014)
Juno 5.1.0.10 is a moderate update.
Core
- Major changes to URL-Encoded serializer and parser.
- Logic for serializing and parsing URL-Encoded key-value pairs moved to
UrlEncodingSerializerandUrlEncodingParserclasses. - Logic for serializing and parsing URL-Encoded values moved to new
UonSerializerandUonParserclasses.
- Logic for serializing and parsing URL-Encoded key-value pairs moved to
- Fix bug where
BeanRuntimeExceptionsweren't being thrown on subsequent calls toBeanContext.getClassMeta(Class). - Moved logic for
BeanContext.getPrimitiveDefault(Class)to newClassMeta.getPrimitiveDefault()method for performance reasons. - Fixed bug in
BeanContext.addTransforms(Class[]) ClassMeta.newInstance()can now create array instances.- Fixed indentation bugs in
HtmlSerializer. - Fixed issue in
HtmlSerializerwhere newlines were not being converted into line breaks. - New
WriterSerializer.toString(Object)method that's identical to the serialize method but throwsRuntimeExceptionsto make the serializer easier to use for debugging.
Server
- Fixed major issue that prevented parsing URL-Encoded form posts into POJOs.
Calling
HttpServlet.getParameter(String)UrlEncodingSerializerclass from being able to parse the content. Updated code no longer inadvertantly calls this method. - New
RestRequest.getQueryParameter(String)RestRequest.hasQueryParameter(String)RestRequest.hasAnyQueryParameters(String[]) - New
@QParam@HasQParam &plainTextparameter can now specify a false value.- Removed properties parameters from
RestServlet.onPreCall(RestRequest)RestServlet#onPostCall(RestRequest,RestResponse)RestRequest.getProperties(). - Added
UonSerializerandUonParserto serializer and parser lists onBasicRestServletandRestServletJenaDefault
Client
- Moved to Apache HttpClient 4.3 to match Jazz 6.0.
- Renamed
RestResponseEntitytoRestRequestEntity. - Improved performance on URL-Encoded form posts by serializing directly to output stream instead of serialized to string first.
- New methods on
RestClientclass that makes it easier to associate serializer and parser attributes with registered serializer and parser:RestClient#setProperty(String,Object)RestClient#setProperties(ObjectMap)RestClient#addNotBeanClasses(Class[])RestClient.addTransforms(Class[])RestClient#addImplClass(Class,Class)
- Renamed
RestClient.shutdown()toRestClient.close()to mirror change in Apache API.
Samples
- New
CodeFormatterResourcefor quickly formatting Java and XML code samples in Javadocs. - New
UrlEncodedFormResourcefor showing how to work with URL-Encoded form posts.
5.1.0.9 (Dec 1, 2014)
Juno 5.1.0.9 is a major update. There weren't very many code changes, but the source has been made a part of Jazz Foundation. This required some restructuring of the project. The project on Jazz Hub will eventually be discontinued. However, the libraries on IBM Community Source will continue to be updated regularly.
- Project split up into 3 separate bundles:
org.apache.juneau- Core serializers and parsers.org.apache.juneau.rest- REST server component.org.apache.juneau.rest.client- REST client component.
- Code changes to facilitate breaking up bundles:
org.apache.juneau.rest.labels.Linkclass moved toLink- References to
org.apache.juneau.rest.RestExceptioninEncoderclass changed toIOException.
- Changed configuration names for consistency with Jazz Framework.
- New
RestClient.execute(HttpUriRequest)method that allows subclasses to handle their own HTTP request execution. - Changes in
JazzRestClientto handle introduction of SSO support in v6. &plainTextdebug feature was broken.- Removed double-buffering in
RestRequest. - Metadata cleanup, Find Bug fixes.
5.1.0.8 (Oct 25, 2014)
Juno 5.1.0.8 is a moderate update, focused primarily on performance improvements.
- Improved performance on JSON and URL-Encoding parsers by approximately 50% on large data sets.
- Rewrote
ParserReaderclass to handle it's own buffering. The change allowed several optimizations to be made when dealing with JSON and URL-Encoding text by avoiding char array copies. - Added a
estimatedSizeparameter to theParserparse methods to optimize buffering when the input size is known beforehand.
- Rewrote
- Revamped the
BeanContextAPI to perform better in multi-threaded environments.- Introduced a new
BeanPropertyStoreclass that handles creation ofBeanContextobjects. This allowsBeanContextobjects 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.
- Introduced a new
- Modifications to the
org.apache.juneau.rest.clientAPIs to make it easier to work with custom Apache HTTP clients.- Added overridable
RestClient#createHttpClient() - Removed the
DefaultRestClientclass since it's now fully redundant withRestClient. - Added
RestClient.shutdown()method for cleaning up the internal HTTP client when you're done using a REST client.
- Added overridable
5.1.0.7 (Oct 5, 2014)
Juno 5.1.0.7 is a moderate update.
- Improved error handling.
- New
ParserContext.PARSER_debugSerializerContext.SERIALIZER_debug - New
Serializer.SERIALIZER_ignoreRecursionssetting for explicitely ignoring recursions when serializing models. Previously, theSERIALIZER_detectRecursions setting did this, but now it simply looks for recursions and throws exceptions when they occur. - Improved handling of
StackOverflowErrors. WhenSERIALIZER_detectRecursions is enabled, a useful error message is displayed showing the exact chain of objects that resulted in the stack overflow. - Bug fixes in
ResultSetListfor Oracle and SQL Server. - Serializers and parsers can now access HTTP request attributes, parameters, and headers through
SerializerContext.getProperties()andParserContext.getProperties(). - Removed media-type and encoding attributes from
SerializerContextParserContext XmlParsernow acceptsapplication/xml.- Improved handling of bean property serialization when multiple matching pojo filters for the bean property class exist.
- Improved concurrency on BeanContext class.
- Fixed bug in
Traversablethat was causing it to be executed even if the servlet extra path info was empty. - Fixed bug in
Traversablewhere it was not picking up filters and properties defined on REST Java methods.
5.1.0.6 (Sept 21, 2014)
Juno 5.1.0.6 is a moderate update.
- Simplified API for
PojoSwap. Since it's rarely used, thebeanContextparameter was replaced with aPojoSwap#getBeanContext() - New simplified way of defining POJO filters without needing to extend
PojoSwap. SeeSurrogateSwapfor details. - New
@Htmlannotation. Will allow the definition of standard XHTML DTOs in future releases. For now,Img JsonParsernow ignores trailing';'characters in input so that it can parse strings of the form"var x = {'foo':'bar'};" .- New
TumblrParserResourcein the samples war file showing how to combine the REST client and server APIs into a single resource in order to download Tumblr blogs and convert the response into any supported response content type.
5.1.0.5 (Sept 1, 2014)
Juno 5.1.0.5 is a moderate update.
- New
Redirectclass that simplifies performing redirections in REST methods. - New pluggable
ResponseHandlerclass and@RestResource.responseHandlers()annotation for defining customer response handlers for special kinds of POJOs. - New method
UrlEncodingSerializer.serializeUrlPart(Object) - New method
RestRequest.getServletURIBuilder() - New method
RestResponse.getNegotiatedOutputStream()that uses encoders if a match is found, andRestResponse.getOutputStream()that just return the underlying output stream without any modifications. - Fixed bug where some properties were not being propagated correctly when using
CoreObject.setProperties(ObjectMap) - Fixed bug in
HtmlSerializerwhere URL keys in Maps were not being serialized as hyperlinks. - Fixed bug in
JsonSerializerwhere"_class" and"items" attributes were not quoted in strict mode when using SERIALIZER_addClassAttrs feature. - Fixed bug where
Content-EncodingandCharacter-Encodingheaders were being set when callingRestResponse.getOutputStream(). These should not be set if interacting with the output streams at a low level. - Eliminated various convenience
RestResponse.sendRedirect(...)methods due to the introduction of theRedirectclass.
5.1.0.4 (Aug 25, 2014)
Juno 5.1.0.4 is a minor update.
- New
RestServlet.getPath() - New
SerializerContext.getJavaMethod()andParserContext.getJavaMethod()to allow access to REST methods that invoked the serializers or parsers. For example, can be used to access additional annotations on REST methods to perform special handing during serialization or parsing. - Better behavior on overriding of filters in
BeanContext.addTransforms(Class[]). Previously, adding multiple conflicting filters resulted in random behavior. Now filters are overridden when multiple matching filters are applied. - Allow
HtmlDocSerializerContextSerializer.setProperty(String,Object) - Fixed memory leak in XML parser.
5.1.0.3 (Jun 28, 2014)
Juno 5.1.0.3 is a moderate update.
Core API updates
- Ability to detect and use non-public bean classes, getters/setters, and fields using the following new properties:
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.andINCLUDE_BEAN_FIELD_PROPERTIES BeanContext.properties, since ignoring fields and methods can be accomplished by setting the appropriate properties above toINCLUDE_BEAN_METHOD_PROPERTIES NONE. Also, the@BeanPropertyannotation can now be used on non-public fields/getters/setters to override the default behavior defined by theVISIBILITYproperties identified above. This is a convenient way of identifying protected or private fields or methods as bean properties. Previously, you could only identify public fields/getters/setters using this annotation. - New
BeanContext.BEAN_useJavaBeanIntrospectorproperty that lets Juno use the Java beanIntrospectorclass to determine bean properties. In the previous release, the method for determining bean properties was a mixture of Juno-based and Introspector-based. Now it's either pure Juno-based or pure Introspector-based. The result is considerably cleaner code and consistent behavior. - New
@BeanIgnoreannotation. Replaces the previous@BeanProperty (hidden=true ) - Support for parsing into non-static member classes. This applies to all parsers.
- New
@Json.wrapperAttr()annotation that automatically wraps beans and objects in a wrapper attribute when serializing to or parsing from JSON. - Changed the default ordering of bean properties to be in parent-to-child class order.
- New
readProperty()andwriteProperty()methods added toBeanFilterclass to allow individualized serialization and parsing behavior on a class-by-class basis. - Eliminated previous restriction where bean subtype attributes had to be listed first in JSON objects when using the
Bean.subTypeProperty() - New fluent-style
BeanMap.load()methods for initializing bean maps. HtmlDocSerializerwill now embed the data portion of the output in a<div id ='data' >
REST Server API updates
- New
RestRequest.getJavaMethod()method for getting access to the method used to handle a request. Useful for accessing the method name or annotations during requests, such as in calls toRestGuard.guard(RestRequest,RestResponse). - Fixed bug when using Jetty where you tried to read text input after a header was written.
- Added new string variables
$A{...}$P{...}RestServlet.createRequestVarResolver(RestRequest).
5.1.0.2 (Apr 27, 2014)
Juno 5.1.0.2 is a minor update.
- Fixed issue preventing
&Accept-Languagefrom being used as a GET parameter. - Minor XSS vulnerability fix.
- Empty results on HTML pages now shows
"no results" instead of a blank page. - Fixed issues preventing REST pages from rendering HTML in newer versions of Internet Explorer.
- Changed
RestServletProperties.REST_allowMethodParamto be disabled by default.
5.1.0.1 (Jan 25, 2014)
Juno 5.1.0.1 is a minor update.
- Addressed some behavioral differences between Tomcat and WAS.
- Query parameter lookup is now always case-insensitive (per WAS behavior).
- Consistent handling of redirect requests (Tomcat and WAS handle relative redirect paths differently).
- Fixed bug involving incorrect resolution of overlapping URL match patterns.
- Overall improvements in HTTP request parameter and header value resolution.
- Made workspace changes so as not to be dependent on the WAS test environment being loaded.
- Renamed
@Remainder annotation to@PathRemainder. - Fixed bug involving incorrect calculation of
pathInfoon child resources.
5.1.0.0 (Jan 18, 2014)
Juno 5.1.0.0 is a major update.
Major changes
- Brand new REST client API that uses Apache HttpClient for HTTP communication.
The new client API is simply a thin layer on top ofHttpClientthat performs serialization and parsing using Juno parsers, but leaves all the details of the HTTP connection to the Apache code.
See theorg.apache.juneau.rest.clientpackage for details. - New
org.apache.juneau.rest.client.jazzpackage andorg.apache.juneau.rest.client.jazz.JazzRestClientclass for performing REST operations against Jazz servers.
Includes improved support for FORM authentication, and better SSL certificate validation. - Completely redesigned URL-Encoding support.
See org.apache.juneau.urlencoding package for details. - Changes to Parser API.
- Removal of
ExtendedReaderParserabstract class and moved methods intoReaderParserclass. - Removal of
DataFormatclass from API since it was no longer necessary due to API change above. - Removal of
ParserStringReaderclass.
This was a reader optimized to work withStringinput.
However, it could interfere with garbage collection of the original string object.
Instead, the existingParserReaderwas enhanced to work well withStringinput, and tests show no significant performance differences. - New
org.apache.juneau.parser.Parser.parse(Object,int,ClassMeta)convenience method added.
- Removal of
Other changes
- Various new methods added to
StringUtilsandClassUtils. - Improved support on
BeanContext.getClassMetaFromString(String)
Now supports resolving"long[]", and so forth. ResourceDescriptionname parameter is now automatically URL-encoded in links.RestRequestnow correctly handles cases involving URL-encoded characters in the path info portion of URLs (e.g.http://host/contextRoot/foo%2Fbar).- Removed lazy-initialization that required locking in
ClassMeta. - New
BeanContext.setDefaultParser(ReaderParser)method added for specifying a default parser to use in a bean context (used when converting beans toStringsusingBeanContext.convertToType(Object,Class) - More consistent handling of exceptions across all parsers.
- Minor changes to
RestRequestclass.- Changed the order of parameters on
RestRequest#getParameter(String,Class) - Added
RestRequest.getMapParameter(String,Class,Class,Class)andRestRequest.getCollectionParameter(String,Class,Class)}methods.
- Changed the order of parameters on
5.0.0.36 (Dec 18, 2013)
Juno 5.0.0.36 is a minor update.
- Implemented
org.apache.juneau.urlencoding.UrlEncodingParser.parseArgs(Reader,int,ClassMeta[]). nameparameter ofResourceDescription#ResourceDescription(String,String,String)"foo/bar(baz)" ).- Support for URL-matching and path info containing encoded characters (e.g.
'/' ) now supported. - Removed some lazy-initialization of bean information in
ClassMetathat allowed the removal of some synchronized blocks. - Improved support of
BeanContext.getClassMetaFromString(String)"long[]" in addition to the previous support for the equivalent"[J" . - Various new convenience methods added to
StringUtilsandClassUtils.
5.0.0.35 (Nov 26, 2013)
Juno 5.0.0.35 is a minor update.
RestGuard.guard(RestRequest,RestResponse)now returns a boolean to allow redirects to login pages.- Fixed bug in RestServlet where occasional false positive "duplicate method with same name and path" errors were occurring.
5.0.0.34 (Nov 10, 2013)
Juno 5.0.0.34 is a moderate update.
-
New support for runtime-replaced variables in REST resource properties:
See@RestResource ( messages="nls/Messages" , properties={@Property (name="label" ,value="$L{servletTitle}" ),// Localized variable in Messages.properties @Property (name="javaVendor" ,value="$S{java.vendor}" ),// System property @Property (name="foo" ,value="bar" ),@Property (name="bar" ,value="baz" ),@Property (name="v1" ,value="$R{foo}" ),// Request variable. value="bar" @Property (name="v2" ,value="$R{$R{foo}}" )// Nested request variable. value="baz" } )RestServlet.createRequestVarResolver(RestRequest)for more information. -
Eliminated
@Property.type annotation which was the old way of specifying NLS variables that got resolved at runtime. -
New methods on
RestRequest:RestRequest.getVarResolver()RestRequest.getServletURI()RestRequest.getRequestParentURI()
-
New methods on
RestResponse:RestResponse.sendRedirect(CharSequence)
-
New methods on
RestServletthat allow easier customization by subclasses:RestServlet.createConfigFactory()RestServlet.createConverters()RestServlet.createDefaultRequestHeaders()RestServlet.createDefaultResponseHeaders()RestServlet.createEncoders()RestServlet.createFilters()RestServlet.createGuards()RestServlet.createMimetypesFileTypeMap()RestServlet.createParsers()RestServlet.createProperties()RestServlet.createRequestProperties(ObjectMap,RestRequest)RestServlet.createRequestVarResolver(RestRequest)RestServlet.createSerializers()RestServlet.createUrlEncodingParser()
-
Changed
RestServletNlsto useResourceDescription/MethodDescriptioninstead ofRestResource/RestMethod -
New property
RestServletProperties.REST_htDocsFolder.
New support for serving up static documents from classpath through REST interface. -
Exception APIs now use
MessageFormat(e.g."{0}" ) for message variables instead of"%s" . -
New
@Bean.stopClassannotation for specifying stop classes for bean properties. -
New
BeanFilter.setStopClass(Class) -
New methods on
ResultSetList:ResultSetList.handleBlob(Blob)ResultSetList.handleClob(Clob)
5.0.0.33 (Oct 20, 2013)
Juno 5.0.0.33 is a moderate update.
-
Removed generic parameter from
WriterSerializerclass.-
Many of the examples in the documentation were written as follows, which resulted in "unchecked" compile warnings:
WriterSerializer s =new JsonSerializer();
These compile warnings will now go away.
-
Many of the examples in the documentation were written as follows, which resulted in "unchecked" compile warnings:
- New settings in BeanContext. These can be applied to all serializers/parsers.
-
Eliminated
addNotBeanClassPatterns(String...)methods throughout API since these are now controlled byBeanContext.BEAN_notBeanPackages_add/BeanContext.BEAN_notBeanPackages_removeproperties. -
New settings in
RestServletProperties.RestServletProperties.REST_trimTrailingUriSlashes
Also removedRestRequest.getRequestURI(boolean trimTrailingSlashes)method which is now redundant with this property.RestServletProperties.REST_pathInfoBlankForNull
Also removedRestRequest.getPathInfo(boolean returnBlankForNull)method which is now redundant with this property.
-
New JSON-Schema
SchemaMapclass for supporting linked schemas. -
Serializers will no longer throw an exception when
maxDepthsetting is reached, and will instead simply ignore content below the specified depth.
While the old behavior was as-designed, the new behavior is more in-line with expected behavior. -
Added support for HTTP header
"X-Response-Headers" toRestServlet.
Allows you to specify one or more headers that should be returned on the response from the servlet.
For example, to get a page to automatically refresh every 1 second, you can append the following to a URL:?x-response-headers={Refresh=1} -
Removed
HtmlDocSerializerContext.setting that added a Refresh meta tag to HTML documents, since this can now be controlled throughHTML_REFRESH X-Response-Headers. -
Small improvements to samples.
PhotosResourcenow includes a default entry.
5.0.0.32 (Oct 5, 2013)
Juno 5.0.0.32 is a moderate update.
-
New support for generating and consuming fully-compliant JSON-Schema documents.
See org.apache.juneau.dto.jsonschema for information. -
New methods added to
Parser:org.apache.juneau.parser.Parser.parseMap(Object,int,Class,Class,Class)org.apache.juneau.parser.Parser.parseCollection(Object,int,Class,Class)
-
@Beanannotation can now be defined on interfaces and inherited by subclasses. -
Support for customizing serialized values for
Enumsthrough overridingtoString()andfromString()on the enum class.
Previously usedEnum.valueOf()to convert strings back intoEnums.
Used for JSON-Schema support to allowJsonTypeenum to be serialized to lowercase per the specification (e.g."string" instead of"STRING" ). -
CognosDTOs now have fluent-style bean setters. -
Support for generic bean objects whose type was erased at compile time.
Previous behavior gave you an error message that the type could not be determined.
New behavior assumes a type ofObjectwhen the type is erased. -
Bug fixes:
-
When duplicate fluent-style setters were defined with different parameter types (e.g.
setFoo(Foo f),setFoo(Bar b)), theBeanMapAPI would sometime choose the wrong setter as the bean property setter.
Now validates that the setter being chosen is the one whose return type matches the property getter. -
Passing in
AcceptGET parameters with'+' (e.g.&Accept=text/json+simple) wasn't working anymore.
TheAcceptparameter is supposed to interpret spaces as'+' to allow you to not have to write&Accept=text/json%2Bsimple. -
Parsers would not set bean properties of abstract type
Number.
Now it detects the numeric type based on input and sets the value accordingly.
-
When duplicate fluent-style setters were defined with different parameter types (e.g.
5.0.0.31 (Aug 9, 2013)
Juno 5.0.0.31 is a moderate update.
-
Simplified the
SerializerandParserclass hierarchies.
This reverses a previous change that added a bunch of interfaces in these APIs (and subsequently required compiling with Java 7 to get around a compiler bug).
The new class hierarchy is much simpler to understand. -
Added
XMLGregorianCalendarSwapto convert these to ISO8601 strings during serialization, and vice versa during parsing. -
Added a strict mode to
JsonParser. -
Added default
JsonParser.DEFAULT_STRICTparser.
5.0.0.30 (Aug 8, 2013)
Juno 5.0.0.30 is a minor update.
-
Fixed bug involving beans using
Bean.subTypes()subTypesproperty. - Modified the JSON parser to handle non-existent JSON values to get around an issue where Cognos was generating invalid JSON.
5.0.0.29 (Aug 2, 2013)
Juno 5.0.0.29 is a moderate update.
-
Revamped the API for filter support:
- Updated
BeanFilterclass to mirror the@Beanannotation. - Introduced support for bean
Bean.subTypeProperty() subtypes - Replaced
@Bean (filter=xxx)@Transform
- Updated
-
Revamped URL-Encoding support.
The old URL-Encoding serializer and parser simply used the JSON serializer/parser with a thin URL-encoding top layer.
The new URL-Encoding serialize and parser was written from scratch and is considerably more consistent in design and output. -
Improved number parsing.
The new number parser should handle any valid numeric syntax for decimals and floats that Java itself supports. -
JsonSerializerLAX mode now quotes reserved word attributes. -
New predefined DateFilters with millisecond precision:
org.apache.juneau.transforms.DateSwap.ISO8601DTPorg.apache.juneau.transforms.DateSwap.ISO8601DTZP
5.0.0.28 (July 9, 2013)
Juno 5.0.0.28 is a moderate update.
-
Fixes an
OutOfMemoryErrorand performance issue caused by incorrect caching of class metadata. -
Added
WriterSerializer.serialize(Object,Writer)convenience method for serializing directly to a writer.
Applies to all serializers.
5.0.0.27 (July 7, 2013)
Juno 5.0.0.27 is a moderate update.
-
Fixed some HTML formatting issues in
HtmlSerializer. -
BasicRestServletnow includesPlainTextSerializerandPlainTextParserfor plain-text support. -
Child resources now render on default
OPTIONSpages through new methodResourceOptions.getChildren() -
Changes to
UrlEncodingSerializer/UrlEncodingParserto reduce the need for quoted string values.
More changes are likely in this area of the code to support multipart form posts. - FindBugs fixes.
5.0.0.26 (Jun 5, 2013)
Juno 5.0.0.26 is a minor update.
- FindBug fixes.
-
Changed the way child REST resources are defined.
Eliminated the@RestChild annotation on getter methods and replaced it with@RestResource.children()defined on the resource class itself.
Child resource paths are specified through@RestResource.path(). -
New
ChildResourceDescriptionsbean for automatically generating the contents of router resource pages. -
Changed
@RestMethod .pattern()@RestMethod.path()for naming consistency.
5.0.0.25 (May 11, 2013)
Juno 5.0.0.25 is a minor update.
Core API updates
-
New
ResultSetListDTO for serializing SQL result sets to JSON/XML/HTML and so forth. -
New
SqlQueryResourceclass in the sample war for demonstrating theResultSetListDTO.
Server API updates
-
Fixed issue with media type for CSS files being reported as
"text/plain" instead of"text/css" . -
Moved initialization of class properties to before the call to
Servlet.init()so thatgetProperties()can be called during servlet initialization. -
New
@Property .type
5.0.0.24 (May 9, 2013)
Juno 5.0.0.24 is a major update.
Core API updates
-
New support for
ATOM.- New
AtomFeedResourceclass added to sample war.
- New
-
New
XmlFormat.CONTENT
Allows bean properties to be persisted as XML element text. -
New
XmlContentHandler@Xml.contentHandler
Allows customized serialization and parsing of beans to XML element text.
Added for support of ATOM text content that must support both plain text and embedded XHTML. -
New
@XmlSchemaand updated@XmlNsannotations to better mimic JAXB. -
Removed
@Xml .valAttr@Xml (format=CONTENT ) -
Fixed timezone bug in
CalendarSwap. -
Simplified
Serializer.serialize(Object,Object,SerializerContext)method. -
Fixed bug where lists returned by
ObjectMap.getObjectList(String)were not updatable. - Eliminated old RDF/XML serializer.
Documentation updates
- New
JSON Support Overviewdocument. - New
XML Support Overviewdocument. - New
RDF Languages Support Overviewdocument. - New
ATOM Support Overviewdocument.
5.0.0.23 (Apr 14, 2013)
Juno 5.0.0.23 is a minor update.
-
Simplified
Cognossupport. -
Fixed bug where
@Xml - Javadoc stylesheet improvements.
5.0.0.22 (Apr 12, 2013)
Juno 5.0.0.22 is a minor update.
Core API changes
-
New
@Property .nls()
For example, allows you to set theHTMLDOC_title andHTMLDOC_description properties to localized values pulled from a resource bundle.
See theAddressBookResourceclass for an example.
REST Servlet API changes
- Fix a bug where the
&Contentquery parameter was not always parsed correctly.
5.0.0.21 (Apr 9, 2013)
Juno 5.0.0.21 is a minor update.
Core API changes
-
New
HtmlDocSerializerContext.HTMLDOC_navlinks -
Renamed the properties in
HtmlDocSerializerContext
Servlet API changes
-
Added new
RestServlet.addDefaultProperties(ObjectMap,RestRequest)method for programatically adding properties to the property map per request. -
Added the following new properties in the properties map to make them easily available to serializers and parsers (since they don't have access to the HTTP request object).
Note that theSerializerContext.SERIALIZER_uriAuthorityandSerializerContext.SERIALIZER_uriContextproperties were previously available.RestServletProperties.REST_servletPathRestServletProperties.REST_pathInfoRestServletProperties.REST_method
-
Path variables annotated with
@Attr
5.0.0.20 (Apr 7, 2013)
Juno 5.0.0.20 is a major update.
Core API changes
-
New Jena-based
RdfSerializerfor serializing POJOs to RDF/XML, RDF/XML-ABBREV, N-Triple, Turtle, and N3.
Serializes ANY POJOs to RDF, even simple objects and primitives. -
New Jena-based
RdfParserfor parsing RDF/XML, RDF/XML-ABBREV, N3, Turtle, and N-Triple back into POJOs. -
XmlSerializerContext.XML_autoDetectNamespacestrue .
The old default value would cause XML with unmapped namespaces if you didn't manually specify them via theXmlSerializerContext.XML_namespaces
While setting the default totrue is somewhat slower (since the serializer must crawl the POJO tree to find namespaces), the benefits of having it work out-of-the-box outweighs the performance concerns.
For developers concerned about performance, they can always change it back to false and specify the namespaces themselves.
REST server API changes
-
Allow inheritance of
@RestResourceannotation.
Serializers, parsers, filters, properties , guards, and converters definitions are automatically inherited from parent classes and interfaces. -
Enhancements to
@RestMethodannotation:-
New
RestMethod.filters()annotation for defining POJO filters at the method level. -
New
RestMethod.serializersInherit()RestMethod.parsersInherit()
This replaces the previousaddSerializersandaddParsersannotations.
-
New
-
New
RestServletJenaDefault -
New
DefaultJenaProvider -
Eliminated
RestServletChildclass.
It's redundant with the introduction of inheritable annotations. -
New methods on
RestServlet:RestServlet.createConfigFactory()RestServlet.createSerializers()RestServlet.createParsers()
getBeanContext()/getSerializers()/getParsers()methods.
REST client API changes
-
New
RestCall.setDateHeader(String,Object)method for setting ISO8601 datetime headers.
5.0.0.19 (Apr 1, 2013)
Juno 5.0.0.19 is a minor update.
-
New methods on
RestServlet:RestServlet.onPreCall(RestRequest)RestServlet.onPostCall(RestRequest,RestResponse)
-
TRIM_NULLS setting changed toSerializerContext.SERIALIZER_trimNullProperties
New property default istrue . Only applies to bean properties, not map or collection entries.
5.0.0.18 (Mar 27, 2013)
Juno 5.0.0.18 is a moderate update.
The biggest change is the introduction of the RdfSerializer class that uses Jena to generate RDF/XML, RDF/XML-ABBREV, N-Tuple, N3, and Turtle output.
This code should be considered prototype-quality, and subject to change in the future.
There are plans of adding an equivalent RdfParser class in the future, so the serializer logic may need to be tweaked to allow POJOs to be reconstituted correctly in the parser.
The RdfXmlSerializer class should be considered deprecated for now.
However, I'm keeping it around, since it's considerably faster and uses far less memory than the Jena-based serializer since it serializes directly from POJOs to RDF/XML.
It may or may not be removed in the future depending on demand.
Other changes
-
New
JsoParserclass.
5.0.0.17 (Mar 25, 2013)
Juno 5.0.0.17 is a minor update.
-
Charset now passed as a parameter to
IOutputStreamSerializer.serialize()andIInputStreamParser.parse().
5.0.0.16 (Mar 25, 2013)
Juno 5.0.0.16 is a minor update.
-
New
@PropertiesRestResponse.
5.0.0.15 (Mar 24, 2013)
Juno 5.0.0.15 is a moderate update.
-
Juno-Wink integration components that have been requested by many for a long time!
Refer toorg.apache.juneau.rest.jaxrsfor information. -
New
@ProducesISerializer.getMediaTypes()for specifying what media types a serializer produces.
Available when subclassing fromSerializer. -
New
@ConsumesIParser.getMediaTypes()for specifying what media types a parser consumes.
Available when subclassing fromParser.
5.0.0.14 (Mar 23, 2013)
Juno 5.0.0.14 is a major update.
The biggest change is that the RestSerializer, RestParser, RestSerializerGroup, and RestParserGroup classes have been eliminated entirely.
Instead, the existing Serializer, Parser, SerializerGroup, and ParserGroup classes of the core API have been augmented to replace them.
Adoptions will be required if you have previously used these classes.
Core API changes
-
New
org.apache.juneau.serializerpackage.- Entirely reworked class hierarchy to make it easier to define new serializers.
- New
WriterSerializerbase class for defining character-based serializers. - New
OutputStreamSerializerbase class for defining byte-based serializers. - Updated
SerializerGroupclass with full support for RFC2616Accept-Contentheaders. - Improved cloning support on serializers and serializer groups.
-
New
org.apache.juneau.parserpackage.- Entirely reworked class hierarchy to make it easier to define new parsers.
- New
ReaderParserbase class for defining character-based parsers. - New
InputStreamParserbase class for defining byte-based parsers. - Improved cloning support on parsers and parser groups.
-
New
org.apache.juneau.transformpackage.- Cleaner class structure.
- Improved
BeanFilterclass for defining property filters on beans. - Improved
PojoQueryclass for defining filters on objects (previously calledObjectFilter).
-
New
org.apache.juneau.encoderspackage.- Defines API for
Encodersfor enabling compression in REST servlets and clients. - Previously, gzip compression was enabled by default. This new API allows you to plug in your own compression algorithms.
- New
GzipEncoderclass for enabling gzip compression. - New
EncoderGroupclass for managing multiple encoders and finding them based on RFC2616Accept-Encodingheader values.
- Defines API for
-
New
org.apache.juneau.plaintextpackage.- New
PlainTextSerializerandPlainTextParserclasses for serializing/parsing text/plain content.
- New
-
New
org.apache.juneau.jsopackage.- New
JsoSerializerclass for serializingapplication/x-java-serialized-objectcontent.
- New
-
New
org.apache.juneau.soappackage.- New
SoapXmlSerializerclass for serializingtext/xml+soapcontent.
- New
-
Improved cloning support on the
BeanContextclass.- Better caching. Improved caching performance.
-
JsonMapandJsonListchanged toObjectMapandObjectListto better reflect that they're not limited to just JSON support. -
Renamed
PojoSwaptoPojoQueryto not confuse it with the new Filter API.
REST server API changes
-
Eliminated
org.apache.juneau.rest.serializersandorg.apache.juneau.rest.parserspackages.- All existing REST serializers and parsers merged into the core API.
REST client API changes
-
Simplified
RestClientAPI.- You can now only specify a single serializer or parser per client. This significantly simplifies the code.
- Support for
Encoders.
-
Eliminated
RestCmdLine(since it's essentially redundant with CURL).
5.0.0.13 (Mar 14, 2013)
Juno 5.0.0.13 is a minor update.
Core API changes
-
New support for relative URIs.
- URIs of the form
"foo/bar" are interpreted as relative to the context root of the web application. - URIs of the form
"/foo/bar" are interpreted as relative to the HTTP authority (e.g."http://myhost:9080" ).
- URIs of the form
-
New
SerializerContext.SERIALIZER_uriContextandSerializerContext.SERIALIZER_uriAuthorityserializer properties for specifying values for relative URIs. -
New
@URIannotation that allows you to specify classes and bean properties as URLs that aren'tjava.net.URIorjava.net.URL. -
New
HtmlSerializer.HTML_uriAnchorTextHTML serializer property for tailoring how anchor text is rendered. -
Renamed
BeanProperty#uriannotation toBeanProperty#beanUrito make it clear that this property represents the URI of the bean itself instead of an arbitrary property containing a URI. -
Removed
BeanProperty#idannotation.
REST server API changes
-
Improvements to
RestServletto automatically handle relative URIs in POJOs.SerializerContext.SERIALIZER_uriContextproperty set by default to web app context root.SerializerContext.SERIALIZER_uriAuthorityproperty set by default to the request scheme+hostname+port.
-
Fixed bug involving
Accept-Charsetheader in Chrome that prevented HTML output from rendering correctly in that browser.
Accept-Charsethandling should now be fully W3C compliant.
5.0.0.12 (Mar 10, 2013)
Juno 5.0.0.12 is a minor update.
Core API changes
-
Relaxed method naming conventions when using
@BeanPropertyannotation.
Methods with zero parameters are interpreted as getters, and methods with one parameter are interpreted as setters.
Eliminated theBeanProperty.methodannotation, since it's now unnecessary.
REST server API changes
-
Significantly improved response error messages.
Older messages were rather cryptic. Error conditions should be much easier to debug now. -
New
PlainTextRestSerializerclass for serializing"plain/text" requests.
Useful for debugging purposes. -
ReadersandInputStreamscan now be passed in as@Content
Equivalent to previously callingRestRequest.getInputStream()andRestRequest.getReader(). -
Improved support for the
?debugparameter.
Dumps better information to the log file, such as all header parameters.
5.0.0.11 (Mar 8, 2013)
Juno 5.0.0.11 is a moderate update.
REST server API changes
-
New
UrlEncodingRestSerializerandUrlEncodingRestParserclasses.
Allows parsing form posts directly to POJOs. -
Support for
AcceptandContent-Type"application/x-www-form-urlencoded" added by default onBasicRestServlet. -
New
RestServlet.renderError(HttpServletRequest,HttpServletResponse,RestException)
5.0.0.10 (Mar 7, 2013)
Juno 5.0.0.10 is a minor update.
Core API changes
- New
ObjectMap.findKeyIgnoreCase(String)method. - HtmlSerializer will now create 2-dimensional tables for collections of mixed beans/maps if all object have the same set of property names/keys.
REST server API changes
- New
RestServletPropertiesclass that defines all the class-level properties that can be set on the servlet. - Properties can be set through
@RestResource.propertiesannotation, or newRestServlet.setProperty(String,Object) - New
"?noTrace" URL parameter to prevent stack traces from being logged (for JUnit testing of error conditions). - New
RestServletProperties.REST_useStackTraceHashesproperty to prevent the same stack trace from being logged multiple times. - New
RestServletProperties.REST_renderResponseStackTracesproperty for preventing stack traces in responses for security reasons. - New overridable
RestServlet.onError(HttpServletRequest,HttpServletResponse,RestException,boolean)andRestServlet.onSuccess(RestRequest,RestResponse,long) - Eliminated
RestServlet.getInitParams()method, since it's now redundant withRestServlet.getProperties(). - Header parameters passed as URL parameters are now case-insensitive.
5.0.0.9 (Feb 26, 2013)
Juno 5.0.0.9 is a moderate update.
Core API changes
-
INI config file support:- A convenient API for reading, writing, and manipulating INI files.
- Ability to convert INI files to batch and shell environment variables.
- Command-line interface for updating INI files.
- Support for encoded INI file values.
- Support for fluent-style bean setters (setters that return the bean itself).
- Ability to use
@Beanannotation to override bean identification settings. - New
ObjectMap.cast(Class)method to convertObjectMapsdirectly to beans.
REST server API changes
- Build-in default
OPTIONSpages. - New
@RestResource.defaultRequestHeadersand@RestResource.defaultResponseHeadersannotations. - New
@RestMethod.serializers()and@RestMethod.parsers()annotations. - New
@RestMethod.properties()annotation. - New
@RestMethod.defaultRequestHeaders()annotation. - New
@RestMethod.matchers()annotation andRestMatcherclass. ReadersandInputStreamscan be specified on@Content- New
@HasParam - Full RFC2616 support for matching
Acceptheaders to serializers.
Other notes
- Smaller library size (460kB).
5.0.0.8 (Jan 30, 2013)
Juno 5.0.0.8 is a minor update.
-
New
INI filesupport.- Makes reading, updating, and manipulating INI configuration files a snap.
- Supports automatic conversion of data types in line with the functionality of the rest of the product.
- Comments and layout of INI files are persisted during saves.
5.0.0.7 (Jan 20, 2013)
Juno 5.0.0.7 is a major update.
Core API updates
- Combined previous 3 libraries into a single library.
-
New
ParserListenerclass.
Adds ability to find and process unknown bean properties during parsing. -
Enhancements to
XmlParser:- Coalescing support
- Validations support
- Support for replacing entity references
- Resolver support
- Event allocator support
- Trim-whitespace support
-
Enhanced XML support:
-
New
@Xml.formatannotation.
Controls how POJOs get serialized to XML.
Also allows you to collapse collections and arrays. -
New
@Xml.namespacesannotation.
Namespaces can be defined at package, class, method, or field levels. -
New
@Xml.nsUriannotation.
Shortcut for specifying namespace URIs. -
New
@Xml.valAttrannotation.
Serializes a bean property value as an attribute. - Ability to override XS and XSI namespaces on XML and RDF/XML serializers.
- Ability to override RDF namespace on RDF/XML serializer.
- New more-efficient namespace resolution.
-
New
-
New configurable property classes for everything are now structured better and easier to locate and identify through the following new classes:
BeanContextSerializerContextParserContext
-
Enhancements to
BeanContext:-
Ability to mark bean properties as hidden using
@BeanProperty.hidden()so that they don't get serialized. -
Simplified
ClassTypeClassMetaAPI.
Combined 4 classes into a single class. -
New
@Bean.filter@BeanProperty.filter
Used for defining filters on bean classes and bean properties instead of just globally throughBeanContext.addTransforms(Class[]). -
New
PropertyNamerAPI /@Bean.propertyNamerannotation.
Used for customizing bean property names. -
New
@BeanProperty.beanUri@BeanProperty.id
Used for associating beans with URLs and IDs.
Used by XML serializer to add a url attribute on a bean element.
Used by RDF/XML serializer to constructrdf:resourceattributes. -
New
@BeanProperty.properties()annotation. Used for limiting properties on child elements.
-
Ability to mark bean properties as hidden using
-
Automatic support for
URLandURIobjects.- Converted to hrefs in HTML.
- Converted to url attributes in XML.
- Converted to resource:about attributes in RDF/XML.
- Improvements to Javadocs.
-
Improved
PojoQuerysupport.
REST client updates
- GZIP compression support.
- Bug fixes.
REST server updates
-
Support for overriding bean context and serializer properties in a REST method call through new
RestResponse.setProperty(String,Object)
For example, allows you to control whitespace options on a per-request basis. -
Several new annotations on REST servlets:
@RestResource.filters()- Associate post-formatting filters on a resource level.@RestResource.guards- Associate resource-level guards.@RestResource.messages- Associate a resource bundle with a REST servlet. Comes with several convenience methods for looking up messages for the client locale.@RestResource.properties- Override default bean context, serializer, and parser properties though an annotation.
-
Several new annotations on REST methods:
@RestMethod.filters()- Associate post-formatting filters on a method level.@RestMethod.guards()- Associate method-level guards.
-
New annotations on REST method parameters with automatic conversion:
@Attr@Param@PathRemainder- The remainder after a URL pattern match as a String.@Header- An HTTP header value as a parsed POJO.@Content@Method- The HTTP method name as a String.
-
HTTP response content POJOs can now simply be returned from methods instead of calling
RestResponse.setOutput(Object).
5.0.0.6 (Oct 30, 2012)
Juno 5.0.0.6 is a minor update that fixes a small bug in 5.0.0.5.
5.0.0.5 (Oct 29, 2012)
Juno 5.0.0.5 is a major update.
- New
@RestChild -
New
traversableandfilterableattributes added to@RestMethodannotation.
Eliminates the need forPojoResourceandFilteredRestResourceclasses. - Simplified client API. Easier to use when making multiple connections to the same server.
- Support for pluggable authentication in the client API.
- Support for authenticating against Jazz Team Servers.
- Support for rendering package-level Javadocs in REST resources.
- Support for parsing of header values into specific object types.
- Changed default XML representation to not include JSON-type attributes. Produces cleaner XML.
-
New
resourceUriattributed added to@Bean annotation to associate beans with resource URIs.- Used for automatically creating hyperlinks in
HtmlSerializer. - Used for automatically creating
uri attributes inXmlSerializer. - Used for automatically creating
rdf:about attributes inRdfXmlSerializer.
- Used for automatically creating hyperlinks in
5.0.0.4 (Oct 7, 2012)
Juno 5.0.0.4 is a minor update.
-
New
@RestMethodannoation onRestServletmethods.
Allows the usage of URL pattern matching and automatic conversion of URL variables to arguments passed to method handlers.
SeeRestServletfor more information. -
Enhancements to
BeanContext.convertToType(Object,Class)Stringsto classes withfromString(String)/valueOf(String)static methods orT(String)constructors.
5.0.0.3 (Oct 3, 2012)
Juno 5.0.0.3 is a minor update.
-
Support for parsing into read-only beans (i.e. beans with only getters, property values set through constructor args).
To support this, the@BeanConstructorannotation has been added. - Merged separate settings classes back into their base classes (simplifies the API).
-
SerializerGroupsandParserGroupsnow shareBeanContextsto reduce memory consumption of class type metadata.
5.0.0.2 (Sept 28, 2012)
Juno 5.0.0.2 is a minor update.
-
Improvements to Javadocs. Most of the information in the Juno Starters Guide wiki has been moved into the overview and package-level javadocs.
Since the information is now written in HTML, you can now copy and paste the code examples directly from the Javadocs.
The code examples are also syntax-highlighted using CSS. - Support for defining default XML namespaces on packages and classes for the XML and RDF serializers.
-
Restructured the packages along content type support (e.g. all JSON support moved to
org.apache.juneau.json). -
Automatic support for parsing maps with
Enumkeys, and parsingEnumstrings.
This was previously possible using filters, but now it's built-in for all the parsers. -
Replaced the
ObjectList.toXArray()methods with a newelements(Class<T> type)method that's more efficient and avoids creating an unnecessary array. -
Support for parsing into beans with read-only properties.
New@BeanConstructorannotation allows you to specify bean property values to be passed in through a constructor. -
Separated the rest library into separate independent client and server libraries.
Use one, use both, it's up to you.
5.0.0.1 (Jun 14, 2012)
Juno 5.0.0.1 is a moderate update.
- New support for generating XML-Schema documents from POJO models.
- New support for serializing to RDF/XML.
5.0.0.0 (Jun 11, 2012)
Version 5.0 marks a major release milestone for the Juno/JJSON library. It is now available for download from iRAM under the name "Juno (previously JJSON)". The Juno Starters Guide has been updated to reflect new functionality in this release.
-
New name.
Unfortunately, "JJSON" was already trademarked by another similar library. Therefore, it's been renamed "Juno" (after the Roman goddess and wife of Jupiter) which does not appear to have any similar trademark issues (crosses fingers). The name is also a play on the word "Uno", indicating that this is a single simple unifying interface of several kinds of technology. -
Simplified APIs for working with beans.
Significant improvements have been made to the parsers to make it easier to convert serialized POJOs back into their original forms. -
Serializer/Parser classes now directly subclass from
BeanContext.
In previous releases, if you wanted to change the way beans were handled by the serializers and parsers, you had to construct a separate bean map factory and pass it to the serializer or parser. Now, you can call the bean map factory methods directly on the serializer or parser class. -
Simplified Filter API for handling non-standard POJOs.
The API for handling non-standard POJOs has been simplified by introducing the concept of aTransformBeanContextclass (and thus the Serializer and Parser classes too) through theBeanContext.addTransforms(Class[])method.
Two new subclasses ofTransformBeanFilter- Filter POJO beans.PojoSwap- Filter POJOs that aren't beans.
CastandBeanFilterAPIs which were considerably more complicated and puts them under a common API. -
Elimination of
_classattributes in parsable output.
One of the complaints about the previous version of JJSON was that if you wanted to have the resulting JSON or XML be parsable back into beans, you had to enable the"addClassAttrs" property on the bean map factory class so that"_class" attributes could be added to the output.
This requirement is virtually eliminated in v5. In many cases, the parsers are able to determine through reflection what the correct target type is based on the top-level class passed in on the parse method. -
Performance improvements.
Several significant performance improvements have been made in this release.-
New Reader-based JSON parser.
Previously, the JSON parser required that the entire JSON text be loaded into memory as a String before being parsed. The new JSON parser is Reader-based which significantly reduces memory consumption. -
New StAX-based XML parser.
The old XML parser was based on DOM. The new XML parser uses a StAX parser which significantly reduces memory consumption. -
Caching of reflection data in the
BeanMapAPI.
The number of reflection calls have been significantly reduced in theBeanMapAPI code. Reflection is used to determine the class types of property values on beans. This information is now cached and persisted so that the reflection API calls to determine class types are only performed the first time a bean type is encountered. -
Automatic support for GZIP compression/decompression in
RestServlets.
This is completely transparent to the developer. The output writer is negotiated by the framework to automatically handle compression and charset requests without the developer needing to know anything about it.
-
New Reader-based JSON parser.
- Cognos/XML support.
- JSON-schema support.
-
New
PojoIntrospectorclass. -
Significant REST servlet API improvements.
- Defining child resources is considerably simpler now. In addition to the standard doX() methods for handling the requests for the current resource, you can also define getX() methods for returning child resources which automatically become available under the child URL specified by the getter name.
- Initialization of the child resources occurs automatically when the parent resource initialization occurs.
-
Other improvments have been made in the area of automatic negotiation of input and output type streams.
For example, automatic support is provided for GZIP (
Accept-Encoding: gzip) and charsets (e.gAccept-Charset: SJIS) on both incoming and outgoing data. It's all transparent from a developers perspective. The developer simply working with POJOs, and all details about content types, encoding, charsets, and so forth are handled by the framework. -
Support for generating complex
OPTIONSpages for resources.
-
Automatic support for SOAP XML output on
"text/soap+xml" requests againstRestServlet. - Support for XML namespaces.
-
Support for setting the XML root element name by either passing in a parameter on the serializer, or by specifying it via a
@Bean annotation. - Support for loading beans directly from Readers and Strings.
-
Parsing support for POJOs of type
Enum. -
Significant improved support for various flavors of parameterized types, such as subclasses of parameterized types (e.g.
MyBeanList).extends LinkedList<MyBean> - Improved ordering of bean properties (should now be ordered as they are defined in the class).
-
Various default filters provided:
- byte[]<-->Base64 encoded strings
- Date/Calendar<-->ISO8601/RFC822/Long
-
New
HtmlParserandUrlEncodingParserclasses. - HtmlSerializer now produces XHTML.