{@link org.apache.juneau.transform.PojoSwap PojoSwaps} are a critical component of Juneau. They allow the serializers and parsers to handle Java objects that wouldn't normally be serializable.

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

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

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

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

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

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

The {@link org.apache.juneau.BeanMap#get(Object)} and {@link org.apache.juneau.BeanMap#put(String,Object)} methods will automatically convert to swapped values as the following example shows:

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

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

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

The following example shows the BASE64 swap in use:

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

Several PojoSwaps are already provided for common Java objects:

• org.apache.juneau.transforms
  • {@link org.apache.juneau.transforms.ByteArrayBase64Swap}
  • {@link org.apache.juneau.transforms.CalendarSwap}
  • {@link org.apache.juneau.transforms.DateSwap}
  • {@link org.apache.juneau.transforms.EnumerationSwap}
  • {@link org.apache.juneau.transforms.IteratorSwap}
  • {@link org.apache.juneau.transforms.ReaderSwap}
  • {@link org.apache.juneau.transforms.XMLGregorianCalendarSwap}

In particular, the {@link org.apache.juneau.transforms.CalendarSwap} and {@link org.apache.juneau.transforms.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 {@link org.apache.juneau.BeanSession#getLocale()} and {@link org.apache.juneau.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.

Swaps can also be defined per-media-type.

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

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

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

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 {@code swap()} method.
The {@code unswap()} method is simply left unimplemented.

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

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

Here is an example of our one-way swap being used.
Note that trying to parse the original object will cause a {@link org.apache.juneau.parser.ParseException} to be thrown.

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

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

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

Multiple swaps can be associated with a POJO by using the {@link org.apache.juneau.annotation.Swaps @Swaps} annotation:

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

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

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

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

@BeanProperty(swap=MyPojoSwap.class) public MyPojo getMyPojo();

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

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

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

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

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

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

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

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

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

• fromString(String) - {@link java.util.UUID}
• valueOf(String) - {@link java.lang.Boolean}, {@link java.lang.Byte}, {@link java.lang.Double}, {@link java.lang.Float}, {@link java.lang.Integer}, {@link java.lang.Long}, {@link java.lang.Short}, {@link java.sql.Date}, {@link java.sql.Time}, {@link java.sql.Timestamp}
• parse(String) - {@link java.text.DateFormat}, {@link java.text.MessageFormat}, {@link java.text.NumberFormat}, {@link java.util.Date}, {@link java.util.logging.Level}
• parseString(String) - {@link javax.xml.bind.DatatypeConverter}
• forName(String) - {@link java.lang.Class}

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

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

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

The BeanSession parameter allows you access to various information about the current serialization session.
For example, you could provide customized results based on the media type being produced ({@link org.apache.juneau.BeanSession#getMediaType()}).

The following example shows how an HTML5 form template object can be created that gets serialized as a populated HTML5 {@link org.apache.juneau.dto.html5.Form} bean.

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

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

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

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

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

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

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

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

This could be solved with the following PojoSwap.

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

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

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

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

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

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

See Also:

• {@link org.apache.juneau.transform.Surrogate}

The {@link org.apache.juneau.annotation.Bean @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 {@link org.apache.juneau.annotation.Bean#properties() @Bean.properties()} annotation.

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

Bean properties can be excluded using the {@link org.apache.juneau.annotation.Bean#excludeProperties() @Bean.excludeProperties()} annotation.

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

Bean properties can be sorted alphabetically using {@link org.apache.juneau.annotation.Bean#sort() @Bean.sort()}

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

The {@link org.apache.juneau.annotation.Bean#propertyNamer() @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 {@link org.apache.juneau.PropertyNamerDLC} will convert property names to dashed-lowercase, and these will be used as attribute names in JSON and element names in XML.

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

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

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

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

The {@link org.apache.juneau.annotation.Bean#stopClass @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 {@link java.beans.Introspector#getBeanInfo(Class, Class)}.
Any properties in the stop class or in its base classes will be ignored during analysis.

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

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

The {@link org.apache.juneau.annotation.Bean#propertyFilter() @Bean.propertyFilter()} annotation and {@link org.apache.juneau.transform.PropertyFilter} class can be used to perform interception and inline handling of bean getter and setter calls.

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

The {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} annotation is used to tailor how individual bean properties are interpreted by the framework.

The {@link org.apache.juneau.annotation.BeanProperty#name() @BeanProperty.name()} annotation is used to override the name of the bean property.

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

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

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

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

The following shows various ways of using dynamic bean properties.

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

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

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

• Note that if you're not interested in these additional properties, you can also use the {@link org.apache.juneau.BeanContext#BEAN_ignoreUnknownBeanProperties} setting to ignore values that don't fit into existing properties.

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

The following annotations are equivalent:

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

The {@link org.apache.juneau.annotation.BeanProperty#type() @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 {@link java.lang.InstantiationException} when trying to set these fields.

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

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

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

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

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

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

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

The {@link org.apache.juneau.annotation.BeanProperty#format() @BeanProperty.format()} annotation specifies a String format for converting a bean property value to a formatted string.

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

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

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

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

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

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

The {@link org.apache.juneau.annotation.BeanIgnore @BeanIgnore} annotation is used to ignore classes, fields, and methods from being interpreted as beans or bean components.

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

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

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

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

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

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

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

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

The {@link org.apache.juneau.annotation.ParentProperty @ParentProperty} annotation is used to identify a setter as a method for adding a parent reference to a child object.

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

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

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

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 {@link org.apache.juneau.annotation.BeanConstructor @BeanConstructor} annotation, using builders can often be cleaner.

A typical builder usage is shown below:

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

The code for such a builder is shown below:

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

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

Builders require two parts:

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

The first can be accomplished through any of the following:

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

  public static MyBuilder create() {...}

• A public constructor on the POJO class that takes in a single parameter that implements the {@link org.apache.juneau.transform.Builder} interface.
  The builder class must have a public no-arg constructor.

  public MyPojo(MyBuilder b) {...}

• A {@link org.apache.juneau.annotation.Builder @Builder} annotation on the POJO class.
  The builder class must have a public no-arg constructor.

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

The second can be accomplished through any of the following:

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

  public MyPojo build() {...}

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

  public MyPojo(MyBuilder b) {...}

See Also:

• {@link org.apache.juneau.annotation.Builder}
• {@link org.apache.juneau.transform.Builder}

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.

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

URI resolution is controlled by the following settings:

• {@link org.apache.juneau.serializer.Serializer#SERIALIZER_uriContext}
  Setting that defines the URI contextual information used to resolve relative URIs.
• {@link org.apache.juneau.serializer.Serializer#SERIALIZER_uriRelativity}
  Setting that defines how relative URIs should be interpreted.
  Possible values:
  • {@link org.apache.juneau.UriRelativity#RESOURCE}
    Relative URIs should be considered relative to the servlet URI.
    (e.g. "http://host:port/context-root/servlet-path").
  • {@link org.apache.juneau.UriRelativity#PATH_INFO}
    Relative URIs should be considered relative to the request URI.
    (e.g. "http://host:port/context-root/servlet-path/path-info").
• {@link org.apache.juneau.serializer.Serializer#SERIALIZER_uriResolution}
  Setting that defines the final format of serialized URIs.
  Possible values:
  • {@link org.apache.juneau.UriResolution#ABSOLUTE}
    Resolve to an absolute URL.
    (e.g. "http://host:port/context-root/servlet-path/path-info").
  • {@link org.apache.juneau.UriResolution#ROOT_RELATIVE}
    Resolve to a root-relative URL.
    (e.g. "/context-root/servlet-path/path-info").
  • {@link org.apache.juneau.UriResolution#NONE}
    Don't do any URL resolution.

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

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

The {@link org.apache.juneau.transform.BeanFilter} class is the programmatic equivalent to the {@link org.apache.juneau.annotation.Bean @Bean} annotation.

In practice, it's usually simpler to use the {@link org.apache.juneau.annotation.Bean @Bean} and {@link org.apache.juneau.annotation.BeanProperty @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 {@link org.apache.juneau.transform.BeanFilterBuilder BeanFilterBuilders}.

In the previous examples, we defined this bean annotation:

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

The programmatic equivalent would be:

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

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

• {@link org.apache.juneau.BeanContext#BEAN_beanFilters}
• {@link org.apache.juneau.BeanContextBuilder#beanFilters(Object...)}

For example:

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

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

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

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

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:

• {@link org.apache.juneau.BeanContext#BEAN_beanFilters}
• {@link org.apache.juneau.annotation.Bean#interfaceClass() @Bean.interfaceClass()}
• {@link org.apache.juneau.transform.BeanFilterBuilder#interfaceClass(Class)}

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

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

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

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

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

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

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

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

The annotation equivalent is {@link org.apache.juneau.annotation.Bean#interfaceClass() Bean#interfaceClass()}.

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

The annotation can be used in a couple of ways.

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

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

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

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

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:

• {@link org.apache.juneau.annotation.Bean#stopClass() @Bean.stopClass()}
• {@link org.apache.juneau.transform.BeanFilterBuilder#stopClass(Class)}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Additional Information - org.apache.juneau.json

1. JSON support overview

   1. Example

2. JsonSerializer class

   1. @Bean and @BeanProperty annotations

   2. Collections

   3. JSON-Schema support

   4. Non-tree models and recursion detection

   5. Configurable properties

   6. Other notes

3. JsonParser class

   1. Parsing into generic POJO models

   2. Configurable properties

   3. Other notes

Additional Information - org.apache.juneau.xml

1. XML support overview

   1. XML support overview - example

2. XmlSerializer class

   1. XML support methodology

   2. @Xml annotations

      1. @Bean.typeName()

      2. @Xml.childName()

      3. @Xml.format()

   3. Namespaces

      1. Auto-detection of namespaces

   4. @Bean and @BeanProperty annotations

   5. Collections

   6. XML-Schema support

   7. Non-tree models and recursion detection

   8. Configurable properties

   9. Other notes

3. XmlParser class

   1. Parsing into generic POJO models

   2. Configurable properties

   3. Other notes

Additional Information - org.apache.juneau.html

1. HTML serialization support

2. HTML parsing support

Additional Information - org.apache.juneau.uon

1. UON support overview

   1. Example

2. UrlEncodingSerializer and UonSerializer classes

   1. @Bean and @BeanProperty annotations

   2. Collections

   3. Non-tree models and recursion detection

   4. Configurable properties

   5. Other notes

3. UrlEncodingParser and UonParser classes

   1. Parsing into generic POJO models

   2. Configurable properties

   3. Other notes

Additional Information - org.apache.juneau.urlencoding

1. URL encoding support overview

   1. Example

2. UrlEncodingSerializer and UonSerializer classes

   1. @Bean and @BeanProperty annotations

   2. Collections

   3. Non-tree models and recursion detection

   4. Configurable properties

   5. Other notes

3. UrlEncodingParser and UonParser classes

   1. Parsing into generic POJO models

   2. Configurable properties

   3. Other notes

• 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.

The most common case for configuration values are primitives.

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

The following methods are provided for accessing primitive values:

• {@link org.apache.juneau.config.Config}
  • {@link org.apache.juneau.config.Config#getString(String) getString(String)}
  • {@link org.apache.juneau.config.Config#getString(String,String) getString(String,String)}
  • {@link org.apache.juneau.config.Config#getBoolean(String) getBoolean(String)}
  • {@link org.apache.juneau.config.Config#getBoolean(String,boolean) getBoolean(String,boolean)}
  • {@link org.apache.juneau.config.Config#getInt(String) getInt(String)}
  • {@link org.apache.juneau.config.Config#getInt(String,int) getInt(String,int)}
  • {@link org.apache.juneau.config.Config#getLong(String) getLong(String)}
  • {@link org.apache.juneau.config.Config#getLong(String,long) getLong(String,long)}
  • {@link org.apache.juneau.config.Config#getFloat(String) getFloat(String)}
  • {@link org.apache.juneau.config.Config#getFloat(String,float) getFloat(String,long)}
  • {@link org.apache.juneau.config.Config#getDouble(String) getDouble(String)}
  • {@link org.apache.juneau.config.Config#getDouble(String,double) getDouble(String,long)}

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

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

Numbers can also use hexadecimal and octal notation:

hex1 = 0x12FE hex2 = 0X12FE octal1 = 01234

Strings with newlines get broken into separate lines:

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

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

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

The following methods are provided for accessing POJO values:

• {@link org.apache.juneau.config.Config}
  • {@link org.apache.juneau.config.Config#getObject(String,Class) getObject(String,Class)}
  • {@link org.apache.juneau.config.Config#getObjectWithDefault(String,Object,Class) getObjectWithDefault(String,T,Class)}

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

• Objects convertible from Strings.
• Beans.

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

# A POJO key4 = http://bar

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

Beans are represented as {@link org.apache.juneau.json.JsonSerializer#DEFAULT_LAX Lax JSON} by default:

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

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

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

• {@link org.apache.juneau.config.ConfigBuilder}
  • {@link org.apache.juneau.config.ConfigBuilder#serializer(Class) serializer(Class)}
  • {@link org.apache.juneau.config.ConfigBuilder#serializer(WriterSerializer) serializer(WriterSerializer)}
  • {@link org.apache.juneau.config.ConfigBuilder#parser(Class) parser(Class)}
  • {@link org.apache.juneau.config.ConfigBuilder#parser(ReaderParser) parser(ReaderParser)}

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

• {@link org.apache.juneau.config.Config}
  • {@link org.apache.juneau.config.Config#getObject(String,Parser,Class) getObject(String,Parser,Class)}
  • {@link org.apache.juneau.config.Config#getObjectWithDefault(String,Parser,Object,Class) getObjectWithDefault(String,T,Parser,Class)}

The following methods are provided for accessing arrays:

• {@link org.apache.juneau.config.Config}
  • {@link org.apache.juneau.config.Config#getStringArray(String) getStringArray(String)}
  • {@link org.apache.juneau.config.Config#getStringArray(String,String[]) getStringArray(String,String)}
  • {@link org.apache.juneau.config.Config#getObject(String,Class) getObject(String,Class)}
  • {@link org.apache.juneau.config.Config#getObject(String,Parser,Class) getObject(String,Parser,Class)}

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

key1 = foo, bar, baz

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

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

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

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

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

key1 = [1,2,3]

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

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

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

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

The following methods are provided for accessing maps and collections:

• {@link org.apache.juneau.config.Config}
  • {@link org.apache.juneau.config.Config#getObject(String,Type,Type...) getObject(String,Type,Type...)}
  • {@link org.apache.juneau.config.Config#getObject(String,Parser,Type,Type...) getObject(String,Parser,Type,Type...)}
  • {@link org.apache.juneau.config.Config#getObjectWithDefault(String,Object,Type,Type...) getObjectWithDefault(String,T,Type,Type...)}
  • {@link org.apache.juneau.config.Config#getObjectWithDefault(String,Parser,Object,Type,Type...) getObjectWithDefault(String,T,Parser,Type,Type...)}

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

Examples are shown below:

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

Example:

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

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

Oftentimes, it might be useful to parse into the {@link org.apache.juneau.ObjectList} and {@link org.apache.juneau.ObjectMap} classes that provide the various convenience methods for working with JSON-like data structures:

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

The following methods are provided for accessing binary data:

• {@link org.apache.juneau.config.Config}
  • {@link org.apache.juneau.config.Config#getBytes(String) getBytes(String)}
  • {@link org.apache.juneau.config.Config#getBytes(String,byte[]) getBytes(String,byte[])}

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:

• {@link org.apache.juneau.config.Config#CONFIG_binaryFormat}

For example:

key = Zm9vYmFycw==

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

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

key = Zm9vYm Fycw==

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

• {@link org.apache.juneau.config.Config#CONFIG_binaryLineLength}

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

• {@link org.apache.juneau.svl.vars.IfVar} - $IF{arg,then[,else]}
• {@link org.apache.juneau.svl.vars.SwitchVar} - $SW{arg,pattern1:then1[,pattern2:then2...]}
• {@link org.apache.juneau.svl.vars.CoalesceVar} - $CO{arg1[,arg2...]}
• {@link org.apache.juneau.svl.vars.PatternMatchVar} - $PM{arg,pattern}
• {@link org.apache.juneau.svl.vars.NotEmptyVar} - $NE{arg}
• {@link org.apache.juneau.svl.vars.UpperCaseVar} - $UC{arg}
• {@link org.apache.juneau.svl.vars.LowerCaseVar} - $LC{arg}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The value can then be retrieved using the equivalent parser:

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

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

• {@link org.apache.juneau.config.Config}
  • {@link org.apache.juneau.config.Config#setSection(String,List,Map) setSection(String,List,Map)}
  • {@link org.apache.juneau.config.Config#load(Map) load(Map)}
  • {@link org.apache.juneau.config.Config#load(Reader,boolean) load(Reader,boolean)}
  • {@link org.apache.juneau.config.Config#load(String,boolean) load(String,boolean)}

Changes can then be committed using the {@link org.apache.juneau.config.Config#commit()} method.

The {@link org.apache.juneau.config.store.ConfigMemoryStore} class is simply an in-memory storage location for configuration files.
There is no hard persistence and is used primarily for testing purposes.

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

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

The {@link org.apache.juneau.config.store.ConfigFileStore} is the typical store used for configuration files. It provides the following configurable settings:

• {@link org.apache.juneau.config.store.ConfigFileStore}
  • {@link org.apache.juneau.config.store.ConfigFileStore#FILESTORE_charset FILESTORE_charset}
  • {@link org.apache.juneau.config.store.ConfigFileStore#FILESTORE_directory FILESTORE_directory}
  • {@link org.apache.juneau.config.store.ConfigFileStore#FILESTORE_updateOnWrite FILESTORE_updateOnWrite}
  • {@link org.apache.juneau.config.store.ConfigFileStore#FILESTORE_useWatcher FILESTORE_useWatcher}
  • {@link org.apache.juneau.config.store.ConfigFileStore#FILESTORE_watcherSensitivity FILESTORE_watcherSensitivity}

Example:

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

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

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

Example Store Class:

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

The purpose of the builder class is to simply set values in the {@link org.apache.juneau.PropertyStore} that's passed to the ConfigStore:

Example Builder Class:

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

The ConfigStore class has the following listener methods:

• {@link org.apache.juneau.config.store.ConfigStore}
  • {@link org.apache.juneau.config.store.ConfigStore#register(String,ConfigStoreListener) register(String,ConfigStoreListener)} - Register a listener on the specified config name.
  • {@link org.apache.juneau.config.store.ConfigStore#unregister(String,ConfigStoreListener) unregister(String,ConfigStoreListener)} - Unregister a listener on the specified config name.

Note that this is a different listener than {@link org.apache.juneau.config.event.ConfigEventListener}.
In this case, we're just listening for changed files:

• {@link org.apache.juneau.config.store.ConfigStoreListener}
  • {@link org.apache.juneau.config.store.ConfigStoreListener#onChange(String)} - Called when file changes. New contents are passed in.

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

The {@link org.apache.juneau.rest.RestServlet} class is the entry point for your REST resources.
It extends directly from HttpServlet and is deployed like any other servlet.

When the servlet init() method is called, it triggers the code to find and process the @RestResource annotations on that class and all child classes.
These get constructed into a {@link org.apache.juneau.rest.RestContext} object that holds all the configuration information about your resource in a read-only object.

Most developers are not going to be using the RestServlet class itself, and instead will extend from one of the preconfigured default servlets such as {@link org.apache.juneau.rest.BasicRestServlet}.
The RestServlet class by itself is not configured with any serializers and parsers, and therefore not very useful on it's own.
However, the class does provide a couple of convenience methods to be aware of:

• {@link org.apache.juneau.rest.RestServlet} extends HttpServlet
  • {@link org.apache.juneau.rest.RestServlet#log(Level,String,Object...) log(Level,String,Object...)}
  • {@link org.apache.juneau.rest.RestServlet#log(Level,Throwable,String,Object...) log(Level,Throwable,String,Object...)}
  • {@link org.apache.juneau.rest.RestServlet#getContext() getContext()}

Since this is a servlet, you also have the ability to intercept calls to the init and service methods in your subclass.

The {@link org.apache.juneau.rest.BasicRestServlet} class is a subclass of {@link org.apache.juneau.rest.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:

@RestResource( serializers={ HtmlDocSerializer.class, HtmlStrippedDocSerializer.class, HtmlSchemaDocSerializer.class, JsonSerializer.class, JsonSerializer.Simple.class, JsonSchemaSerializer.class, XmlDocSerializer.class, XmlSchemaDocSerializer.class, UonSerializer.class, UrlEncodingSerializer.class, MsgPackSerializer.class, SoapXmlSerializer.class, PlainTextSerializer.class }, parsers={ JsonParser.class, XmlParser.class, HtmlParser.class, UonParser.class, UrlEncodingParser.class, MsgPackParser.class, PlainTextParser.class }, properties={ // URI-resolution is disabled by default. Need to enable it. @Property(name=SERIALIZER_uriResolution, value="ROOT_RELATIVE") }, allowedMethodParams="OPTIONS", htmldoc=@HtmlDoc( header={ "<h1>$R{resourceTitle}</h1>", "<h2>$R{methodSummary,resourceDescription}</h2>", "<a href='http://juneau.apache.org'><img src='$U{servlet:/htdocs/juneau.png}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/></a>" }, navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS" }, stylesheet="servlet:/styles/light.css", head={ "<link rel='icon' href='$U{servlet:/htdocs/juneau.png}'/>" } ), // Optional external configuration file. config="$S{juneau.configFile}", // These are static files that are served up by the servlet under the specified sub-paths. // For example, "/servletPath/htdocs/javadoc.css" resolves to the file "[servlet-package]/htdocs/javadoc.css" staticFiles={"htdocs:htdocs","styles:styles"} ) public abstract class BasicRestServlet extends RestServlet { // Show resource options. @RestMethod(name=OPTIONS, path="/*", htmldoc=@HtmlDoc( navlinks={ "back: servlet:/", "json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true" }, aside="NONE" ), summary="Swagger documentation", description="Auto-generated swagger documentation for this resource" ) public Swagger getOptions(RestRequest req) { return req.getSwagger(); } }

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.

Child Resources are REST servlets or objects that are linked to parent resources through the {@link org.apache.juneau.rest.annotation.RestResource#children() @RestResource.children()} annotation.

Example:

/** Parent Resource */ @RestResource( path="/parent", children={FooResource.class} ) public MyResource extends BasicRestServlet {...}

/** Child Resource */ @RestResource( path="/foo" // Path relative to parent resource. ) public FooResource {...} // Note that we don't need to extend from RestServlet.

The path of the child resource gets appended to the path of the parent resource.
So in the example above, the child resource is accessed through the URL /parent/foo.

A HUGE advantage of using child resources is that they do not need to be declared in the JEE web.xml file.
Initialization of and access to the child resources occurs through the parent resource.
Children can be nested arbitrary deep to create complex REST interfaces with a single top-level REST servlet.

See Also:

• {@link org.apache.juneau.rest.RestContext#REST_children}

The {@link org.apache.juneau.rest.BasicRestServletGroup} class provides a default "router" page for child resources when a parent resource is nothing more than a grouping of child resources.

The RootResources class in the Samples project is an example of a router page:

/** * Sample REST resource showing how to implement a "router" resource page. */ @RestResource( path="/", title="Root resources", description="Example of a router resource page.", children={ HelloWorldResource.class, MethodExampleResource.class, RequestEchoResource.class, TempDirResource.class, AddressBookResource.class, SampleRemoteableServlet.class, PhotosResource.class, AtomFeedResource.class, JsonSchemaResource.class, SqlQueryResource.class, TumblrParserResource.class, CodeFormatterResource.class, UrlEncodedFormResource.class, SourceResource.class, ConfigResource.class, LogsResource.class, DockerRegistryResource.class, ShutdownResource.class } ) public class RootResources extends RestServletGroup { // NO CODE!!! }

When you bring up this resource in a browser, you see the following that provides a list of navigable links to your child resources:

The {@link org.apache.juneau.rest.BasicRestServletGroup} class is nothing more than a subclass of {@link org.apache.juneau.rest.BasicRestServlet} with a getChildren() method mapped to the servlet root path.
The method returns a POJO with is just a linked-list of beans with name/description properties.

// The entire contents of the RestServletGroup class. public class RestServletGroup extends BasicRestServlet { @RestMethod(name=GET, path="/", description="Child resources") public ChildResourceDescriptions getChildren(RestRequest req) { return new ChildResourceDescriptions(this, req); } }

By default, you can add the {@link org.apache.juneau.rest.annotation.RestResource @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 {@link org.apache.juneau.rest.RestContextBuilder} object to make any configurations to the resource before it's initialized.

Resource object resolution is controlled through the following API:

• {@link org.apache.juneau.rest.RestResourceResolver}
  • {@link org.apache.juneau.rest.BasicRestResourceResolver}

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:

• {@link org.apache.juneau.rest.RestContext#REST_resourceResolver}

Lifecycle hooks allow you to hook into lifecycle events of the servlet/resource creation and REST calls.

For example, if you want to add an initialization method to your resource:

@RestResource(...) public class MyResource { // Our database. private Map<Integer,Object> myDatabase; @RestHook(INIT) public void initMyDatabase(RestContextBuilder builder) throws Exception { myDatabase = new LinkedHashMap<>(); } }

Or if you want to intercept REST calls:

@RestResource(...) public class MyResource { // Add a request attribute to all incoming requests. @RestHook(PRE_CALL) public void onPreCall(RestRequest req) { req.setAttribute("foo", "bar"); } }

The hook events can be broken down into two categories:

• Resource lifecycle events:
  • {@link org.apache.juneau.rest.annotation.HookEvent#INIT INIT} - Right before initialization.
  • {@link org.apache.juneau.rest.annotation.HookEvent#POST_INIT POST_INIT} - Right after initialization.
  • {@link org.apache.juneau.rest.annotation.HookEvent#POST_INIT_CHILD_FIRST POST_INIT_CHILD_FIRST} - Right after initialization, but run child methods first.
  • {@link org.apache.juneau.rest.annotation.HookEvent#DESTROY DESTROY} - Right before servlet destroy.
• REST call lifecycle events:
  • {@link org.apache.juneau.rest.annotation.HookEvent#START_CALL START_CALL} - At the beginning of a REST call.
  • {@link org.apache.juneau.rest.annotation.HookEvent#PRE_CALL PRE_CALL} - Right before the @RestMethod method is invoked.
  • {@link org.apache.juneau.rest.annotation.HookEvent#POST_CALL POST_CALL} - Right after the @RestMethod method is invoked.
  • {@link org.apache.juneau.rest.annotation.HookEvent#END_CALL END_CALL} - At the end of the REST call after the response has been flushed.

See Also:

• {@link org.apache.juneau.rest.annotation.RestHook}

The {@link org.apache.juneau.rest.annotation.RestResource @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.

Java methods can contain any of the following parameters in any order:

• Parameters based on class types:
  • Request/response objects:
    • {@link org.apache.juneau.rest.RestRequest} - The request object.
    • {@link javax.servlet.http.HttpServletRequest} - The superclass of RestRequest.
    • {@link org.apache.juneau.rest.RestResponse} - The response object.
    • {@link javax.servlet.http.HttpServletResponse} - The superclass of RestResponse.
  • Parsed request header values:
    • {@link org.apache.juneau.http.Accept}
    • {@link org.apache.juneau.http.AcceptCharset}
    • {@link org.apache.juneau.http.AcceptEncoding}
    • {@link org.apache.juneau.http.AcceptLanguage}
    • {@link org.apache.juneau.http.Authorization}
    • {@link org.apache.juneau.http.CacheControl}
    • {@link org.apache.juneau.http.Connection}
    • {@link org.apache.juneau.http.ContentLength}
    • {@link org.apache.juneau.http.ContentType}
    • {@link org.apache.juneau.http.Date}
    • {@link org.apache.juneau.http.Expect}
    • {@link org.apache.juneau.http.From}
    • {@link org.apache.juneau.http.Host}
    • {@link org.apache.juneau.http.IfMatch}
    • {@link org.apache.juneau.http.IfModifiedSince}
    • {@link org.apache.juneau.http.IfNoneMatch}
    • {@link org.apache.juneau.http.IfRange}
    • {@link org.apache.juneau.http.IfUnmodifiedSince}
    • {@link org.apache.juneau.http.MaxForwards}
    • {@link org.apache.juneau.http.Pragma}
    • {@link org.apache.juneau.http.ProxyAuthorization}
    • {@link org.apache.juneau.http.Range}
    • {@link org.apache.juneau.http.Referer}
    • {@link org.apache.juneau.http.TE}
    • {@link org.apache.juneau.http.UserAgent}
    • {@link org.apache.juneau.http.Upgrade}
    • {@link org.apache.juneau.http.Via}
    • {@link org.apache.juneau.http.Warning}
    • {@link java.util.TimeZone}
  • Direct streams on request/response:
    • {@link java.io.InputStream}
    • {@link javax.servlet.ServletInputStream}
    • {@link java.io.Reader}
    • {@link java.io.OutputStream}
    • {@link javax.servlet.ServletOutputStream}
    • {@link java.io.Writer}
  • Localization:
    • {@link java.util.ResourceBundle} - Client-localized resource bundle.
    • {@link org.apache.juneau.utils.MessageBundle} - A resource bundle with additional features.
    • {@link java.util.Locale} - Client locale.
  • Request APIs:
    • {@link org.apache.juneau.rest.RequestHeaders} - API for accessing request headers.
    • {@link org.apache.juneau.rest.RequestQuery} - API for accessing request query parameters.
    • {@link org.apache.juneau.rest.RequestFormData} - API for accessing request form data.
    • {@link org.apache.juneau.rest.RequestPathMatch} - API for accessing path variables.
    • {@link org.apache.juneau.rest.RequestBody} - API for accessing request body.
  • Other:
    • {@link org.apache.juneau.http.HttpMethod} - The method name matched (when using @RestMethod(name="*"))
    • {@link org.apache.juneau.rest.RestLogger} - Logger with additional features.
    • {@link org.apache.juneau.rest.RestContext} - The resource read-only context.
    • {@link org.apache.juneau.parser.Parser} - The parser matching the request content type.
    • {@link org.apache.juneau.dto.swagger.Swagger} - The auto-generated Swagger doc.
    • {@link org.apache.juneau.config.Config} - The external config for the resource.
    • {@link org.apache.juneau.rest.RequestProperties} - API for modifying request-time configuration properties.
• Annotated parameters:
  • {@link org.apache.juneau.rest.annotation.Path} - Variables in matched URL path patterns.
  • {@link org.apache.juneau.rest.annotation.FormData} - Multipart form post parameter values.
  • {@link org.apache.juneau.rest.annotation.HasFormData} - Denotes whether the form data parameter exists.
  • {@link org.apache.juneau.rest.annotation.Query} - Query parameters. Using this prevents the HTTP body from being processed as a URL-Encoded form post.
  • {@link org.apache.juneau.rest.annotation.HasQuery} - Denotes whether the query parameter exists.
  • {@link org.apache.juneau.rest.annotation.Header} - A header value.
  • {@link org.apache.juneau.rest.annotation.Method} - The HTTP method name.
  • {@link org.apache.juneau.rest.annotation.PathRemainder} - The remainder value after path pattern match.
  • {@link org.apache.juneau.rest.annotation.Body} - The HTTP content parsed as a POJO.

Example:

@RestMethod(name=GET, path="/example1/{a1}/{a2}/{a3}/*") public String doGetExample1( RestRequest req, RestResponse res, @Method String method, @Path String a1, @Path int a2, @Path UUID a3, @Query("p1") int p1, @Query("p2") String p2, @Query("p3") UUID p3, @HasQuery("p3") boolean hasP3, @PathRemainder String remainder, @Header("Accept-Language") String lang, @Header("Accept") String accept, @Header("DNT") int doNotTrack, RequestProperties properties, ResourceBundle nls ) { // Do something with all of those }

Notes:

• All annotations have programmatic equivalents on the {@link org.apache.juneau.rest.RestRequest} class.

See Also:

• {@link org.apache.juneau.rest.RestContext#REST_paramResolvers} - For configuring custom parameter types.

The {@link org.apache.juneau.rest.RestRequest} object is an extension of the HttpServletRequest class with various built-in convenience methods for use in building REST interfaces.
It can be accessed by passing it as a parameter on your REST Java method:

@RestMethod(...) public Object myMethod(RestRequest req) {...}

There are many useful methods on this object, but the main ones are shown below:

• {@link org.apache.juneau.rest.RestRequest} extends HttpServletRequest
  • {@link org.apache.juneau.rest.RestRequest#getHeaders() getHeaders()}
  • {@link org.apache.juneau.rest.RestRequest#getQuery() getQuery()}
  • {@link org.apache.juneau.rest.RestRequest#getFormData() getFormData()}
  • {@link org.apache.juneau.rest.RestRequest#getBody() getBody()}
  • {@link org.apache.juneau.rest.RestRequest#getPathMatch() getPathMatch()}
  • {@link org.apache.juneau.rest.RestRequest#getLogger() getLogger()}
  • {@link org.apache.juneau.rest.RestRequest#getInfoProvider() getInfoProvider()}
  • {@link org.apache.juneau.rest.RestRequest#getSwagger() getSwagger()}
  • {@link org.apache.juneau.rest.RestRequest#getConfig() getConfig()}
  • {@link org.apache.juneau.rest.RestRequest#getVarResolverSession() getVarResolverSession()}
  • {@link org.apache.juneau.rest.RestRequest#getMessageBundle() getMessageBundle()}
  • {@link org.apache.juneau.rest.RestRequest#getProperties() getProperties()}
  • {@link org.apache.juneau.rest.RestRequest#getClasspathReaderResource(String,boolean,MediaType) getClasspathReaderResource(String,boolean,MediaType)}

The {@link org.apache.juneau.rest.RestResponse} object is an extension of the HttpServletResponse class with various built-in convenience methods for use in building REST interfaces.
It can be accessed by passing it as a parameter on your REST Java method:

@RestMethod(...) public Object myMethod(RestResponse req) {...}

The important methods on this class are shown below:

• {@link org.apache.juneau.rest.RestResponse} extends HttpServletResponse
  • {@link org.apache.juneau.rest.RestResponse#setOutput(Object) setOutput(Object)}
  • {@link org.apache.juneau.rest.RestResponse#getProperties() getProperties()}
  • {@link org.apache.juneau.rest.RestResponse#getHtmlDocBuilder() getHtmlDocBuilder()}
  • {@link org.apache.juneau.rest.RestResponse#getDirectWriter(String) getDirectWriter(String)}

The {@link org.apache.juneau.rest.RequestBody} object is the API for accessing the body of an HTTP request.
It can be accessed by passing it as a parameter on your REST Java method:

@RestMethod(...) public Object myMethod(RequestBody body) {...}

Example:

@RestMethod(...) public void doPost(RequestBody body) { // Convert body to a linked list of Person objects. List<Person> l = body.asType(LinkedList.class, Person.class); ... }

The important methods on this class are:

• {@link org.apache.juneau.rest.RequestBody}
  • {@link org.apache.juneau.rest.RequestBody#getReader() getReader()}
  • {@link org.apache.juneau.rest.RequestBody#getInputStream() getInputStream()}
  • {@link org.apache.juneau.rest.RequestBody#asType(Class) asType(Class)}
  • {@link org.apache.juneau.rest.RequestBody#asType(Type,Type...) asType(Type,Type...)}
  • {@link org.apache.juneau.rest.RequestBody#asString() asString()}
  • {@link org.apache.juneau.rest.RequestBody#asHex() asHex()}
  • {@link org.apache.juneau.rest.RequestBody#asSpacedHex() asSpacedHex()}

The {@link org.apache.juneau.rest.RequestHeaders} object is the API for accessing the headers of an HTTP request.
It can be accessed by passing it as a parameter on your REST Java method:

@RestMethod(...) public Object myMethod(RequestHeaders headers) {...}

Example:

@RestMethod(...) public Object myMethod(RequestHeaders headers) { // Add a default value. headers.addDefault("ETag", DEFAULT_UUID); // Get a header value as a POJO. UUID etag = headers.get("ETag", UUID.class); // Get a standard header. CacheControl = headers.getCacheControl(); }

The important methods on this class are:

• {@link org.apache.juneau.rest.RequestHeaders} extends TreeMap<String,String[]>
  • {@link org.apache.juneau.rest.RequestHeaders#get(String,Class) get(String,Class)}
  • {@link org.apache.juneau.rest.RequestHeaders#get(String,Type,Type...) get(String,Type,Type)}
  • {@link org.apache.juneau.rest.RequestHeaders#getString(String,String) getString(String,String)}
  • {@link org.apache.juneau.rest.RequestHeaders#getInt(String,int) getInt(String,int)}
  • {@link org.apache.juneau.rest.RequestHeaders#getBoolean(String,boolean) getBoolean(String,boolean)}
  • {@link org.apache.juneau.rest.RequestHeaders#addDefault(String,Object) addDefault(String,Object)}

The {@link org.apache.juneau.rest.RequestQuery} object is the API for accessing the GET query parameters of an HTTP request.
It can be accessed by passing it as a parameter on your REST Java method:

@RestMethod(...) public Object myMethod(RequestQuery query) {...}

Example:

@RestMethod(...) public Object myMethod(RequestQuery query) { // Get query parameters converted to various types. int p1 = query.get("p1", 0, int.class); String p2 = query.get("p2", String.class); UUID p3 = query.get("p3", UUID.class); }

An important distinction between the behavior of this object and HttpServletRequest.getParameter(String) is that the former will NOT load the body of the request on FORM POSTS and will only look at parameters found in the query string.
This can be useful in cases where you're mixing GET parameters and FORM POSTS and you don't want to inadvertantly read the body of the request to get a query parameter.

The important methods on this class are:

• {@link org.apache.juneau.rest.RequestQuery} extends LinkedHashMap<String,String[]>
  • {@link org.apache.juneau.rest.RequestQuery#get(String,Class) get(String,Class)}
  • {@link org.apache.juneau.rest.RequestQuery#get(String,Type,Type...) get(String,Type,Type)}
  • {@link org.apache.juneau.rest.RequestQuery#getString(String,String) getString(String,String)}
  • {@link org.apache.juneau.rest.RequestQuery#getInt(String,int) getInt(String,int)}
  • {@link org.apache.juneau.rest.RequestQuery#getBoolean(String,boolean) getBoolean(String,boolean)}
  • {@link org.apache.juneau.rest.RequestQuery#addDefault(String,Object) addDefault(String,Object)}
  • {@link org.apache.juneau.rest.RequestQuery#getSearchArgs() getSearchArgs()}

The {@link org.apache.juneau.rest.RequestFormData} object is the API for accessing the HTTP request body as form data.
It can be accessed by passing it as a parameter on your REST Java method:

@RestMethod(...) public Object myMethod(RequestFormData query) {...}

Example:

@RestMethod(...) public Object myMethod(RequestFormData formData) { // Get query parameters converted to various types. int p1 = formData.get("p1", 0, int.class); String p2 = formData.get("p2", String.class); UUID p3 = formData.get("p3", UUID.class); }

Note that this object does NOT take GET parameters into account and only returns values found in the body of the request.

The important methods on this class are:

• {@link org.apache.juneau.rest.RequestFormData} extends LinkedHashMap<String,String[]>
  • {@link org.apache.juneau.rest.RequestFormData#get(String,Class) get(String,Class)}
  • {@link org.apache.juneau.rest.RequestFormData#get(String,Type,Type...) get(String,Type,Type)}
  • {@link org.apache.juneau.rest.RequestFormData#getString(String,String) getString(String,String)}
  • {@link org.apache.juneau.rest.RequestFormData#getInt(String,int) getInt(String,int)}
  • {@link org.apache.juneau.rest.RequestFormData#getBoolean(String,boolean) getBoolean(String,boolean)}
  • {@link org.apache.juneau.rest.RequestFormData#addDefault(String,Object) addDefault(String,Object)}

The {@link org.apache.juneau.rest.annotation.RestMethod#path() @RestMethod.path()} annotation allows you to define URL path patterns to match against.
These patterns can contain variables of the form "{xxx}" that can be passed in directly to the Java methods as extra parameters.

In the following example, 3 separate GET request handlers are defined with different path patterns.
Note how the variables are passed in as additional arguments on the method, and how those arguments are automatically converted to the specified class type...

// Default method @RestMethod(name=GET, path="/*") public void doGetDefault() { ... } // Method with path pattern @RestMethod(name=GET, path="/xxx") public void doGetNoArgs(...) { ... } // Method with path pattern with arguments @RestMethod(name=GET, path="/xxx/{foo}/{bar}/{baz}/{bing}") public void doGetWithArgs(@Path String foo, @Path int bar, @Path MyEnum baz, @Path UUID bing) { ... }

By default, path patterns are matched using a best-match heuristic.
When overlaps occur, URLs are matched from most-specific to most-general order:

// Try first @RestMethod(name=GET, path="/foo/bar") public void method1() { ... } // Try second @RestMethod(name=GET, path="/foo/{bar}") public void method2(...) { ... } // Try third @RestMethod(name=GET, path="/foo/*") public void method3(...) { ... } // Try last @RestMethod(name=GET, path="/*") public void method4(...) { ... }

The match heuristic behavior can be overridden by the {@link org.apache.juneau.rest.annotation.RestMethod#priority() @RestMethod.priority()} annotation property.
However, in practice this is almost never needed.

Paths that end with "/*" will do a prefix match on the incoming URL.
Any remainder after the match can be accessed through {@link org.apache.juneau.rest.RequestPathMatch#getRemainder()} or parameters with the {@link org.apache.juneau.rest.annotation.PathRemainder @PathRemainder} annotation.
On the other hand, paths that don't end with "/*" (e.g. "/" or "/foo") will require an exact URL match, and if any remainder exists, a 404 (not found) error will be thrown.

The following example shows the distinction.

@RestMethod(name=GET, path="/*") public void doGet(@PathRemainder String remainder) { // URL path pattern can have remainder accessible through req.getRemainder(). } @RestMethod(name=PUT, path="/") public void doPut() { // URL path pattern must match exactly and will cause a 404 error if a remainder exists. }

Annotations are provided for easy access to URL parameters with automatic conversion to any parsable type.
For example, the following example can process the URL "/urlWithParams?foo=foo&bar=[1,2,3]&baz=067e6162-3b6f-4ae2-a171-2470b63dff00"...

// Example GET request with access to query parameters @RestMethod(name=GET, path="/urlWithParams") public String doGetWithParams(@Query("foo") String foo, @Query("bar") int bar, @Query("baz") UUID baz) throws Exception { return "GET /urlWithParams?foo="+foo+"&bar="+bar+"&baz="+baz; }

See Also:

• {@link org.apache.juneau.rest.RestContext#REST_path}
• {@link org.apache.juneau.rest.annotation.Path}
• {@link org.apache.juneau.rest.annotation.PathRemainder}
• {@link org.apache.juneau.rest.RequestPathMatch}

The {@link org.apache.juneau.rest.RequestPathMatch} object is the API for accessing the matched variables and remainder on the URL path.

@RestMethod(...) public Object myMethod(RequestPathMatch path) {...}

Example:

@RestMethod(..., path="/{foo}/{bar}/{baz}/*") public void doGet(RequestPathMatch path) { // Example URL: /123/qux/true/quux int foo = pm.getInt("foo"); // =123 String bar = pm.getString("bar"); // =qux boolean baz = pm.getBoolean("baz"); // =true String remainder = pm.getRemainder(); // =quux }

The important methods on this class are:

• {@link org.apache.juneau.rest.RequestPathMatch} extends TreeMap<String,String>
  • {@link org.apache.juneau.rest.RequestPathMatch#get(String,Class) get(String,Class)}
  • {@link org.apache.juneau.rest.RequestPathMatch#get(String,Type,Type...) get(String,Type,Type)}
  • {@link org.apache.juneau.rest.RequestPathMatch#getString(String) getString(String)}
  • {@link org.apache.juneau.rest.RequestPathMatch#getInt(String) getInt(String)}
  • {@link org.apache.juneau.rest.RequestPathMatch#getBoolean(String) getBoolean(String)}
  • {@link org.apache.juneau.rest.RequestPathMatch#getRemainder() getRemainder()}

The return type can be any serializable POJO as defined in POJO Categories.
It can also be void if the method is not sending any output (e.g. a request redirect) or is setting the output using the {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} method.

Example:

@RestMethod(name=GET) public String doGet() { return "Hello World!"; }

Out-of-the-box, besides POJOs, the following return types are handled as special cases:

• {@link java.io.InputStream}
  The contents are simply piped to the output stream returned by {@link org.apache.juneau.rest.RestResponse#getNegotiatedOutputStream()}.
  Note that you should call {@link org.apache.juneau.rest.RestResponse#setContentType(String)} to set the Content-Type header if you use this object type.
• {@link java.io.Reader}
  The contents are simply piped to the output stream returned by {@link org.apache.juneau.rest.RestResponse#getNegotiatedWriter()}.
  Note that you should call {@link org.apache.juneau.rest.RestResponse#setContentType(String)} to set the Content-Type header if you use this object type.
• {@link org.apache.juneau.rest.Redirect}
  Represents an HTTP redirect response.
• {@link org.apache.juneau.Streamable}
  Interface that identifies that an object can be serialized directly to an output stream.
• {@link org.apache.juneau.Writable}
  Interface that identifies that an object can be serialized directly to a writer.
• {@link org.apache.juneau.utils.ZipFileList}
  Special interface for sending zip files as responses.

This is controlled through the following extensible API:

• {@link org.apache.juneau.rest.ResponseHandler}
  • {@link org.apache.juneau.rest.response.DefaultHandler}
  • {@link org.apache.juneau.rest.response.InputStreamHandler}
  • {@link org.apache.juneau.rest.response.ReaderHandler}
  • {@link org.apache.juneau.rest.response.RedirectHandler}
  • {@link org.apache.juneau.rest.response.StreamableHandler}
  • {@link org.apache.juneau.rest.response.WritableHandler}
  • {@link org.apache.juneau.rest.response.ZipFileListResponseHandler}

REST Java methods can generate output in any of the following ways:

• By returning a serializable POJO, or any of the following:
  {@link java.io.Reader}, {@link java.io.InputStream}, {@link org.apache.juneau.Streamable}, {@link org.apache.juneau.Writable}
• By calling {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} with any of the types above.
• By accessing the {@link java.io.Writer} directly by calling {@link org.apache.juneau.rest.RestResponse#getNegotiatedWriter()} and writing the output yourself.

Example:

// Equivalent method 1 @RestMethod(name=GET, path="/example1/{personId}") public Person doGet1(@Path UUID personId) { Person p = getPersonById(personId); return p; } // Equivalent method 2 @RestMethod(name=GET, path="/example2/{personId}") public void doGet2(RestResponse res, @Path UUID personId) { Person p = getPersonById(personId); res.setOutput(p); } // (Sorta) Equivalent method 3 // (Ignores any converters or method-level properties) @RestMethod(name=GET, path="/example3/{personId}") public void doGet3(RestRequest req, RestResponse res, @Path UUID personId) { Person p = getPersonById(personId); String accept = req.getHeader("Accept", "text/json"); WriterSerializer s = res.getSerializerGroup().getWriterSerializer(accept); res.setContentType(s.getResponseContentType()); s.serialize(p, res.getNegotiatedWriter()); }

See Also:

• {@link org.apache.juneau.rest.RestContext#REST_responseHandlers} - For configuring custom response handlers.

The {@link org.apache.juneau.rest.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 {@link org.apache.juneau.rest.ReaderResource} class implements the {@link org.apache.juneau.Writable} interface which is handled by the {@link org.apache.juneau.rest.response.WritableHandler} class.
This allows these objects to be returned as responses by REST methods.

Example:

@RestMethod(...) public Object sayHello(RestRequest req) { // Return a reader resource loaded from a file with support for request-time SVL variables. return ReaderResource.create() .contents(new File("helloWorld.txt")) .varResolver(req.getVarResolver()) .header("Cache-Control", "no-cache") .mediaType(TEXT_PLAIN) .build(); }

The important methods on this class are:

• {@link org.apache.juneau.rest.ReaderResourceBuilder}
  • {@link org.apache.juneau.rest.ReaderResourceBuilder#contents(Object...) contents(Object...)}
  • {@link org.apache.juneau.rest.ReaderResourceBuilder#header(String,Object) header(String,Object)}
  • {@link org.apache.juneau.rest.ReaderResourceBuilder#mediaType(MediaType) mediaType(MediaType)}
  • {@link org.apache.juneau.rest.ReaderResourceBuilder#varResolver(VarResolverSession) varResolver(VarResolverSession)}

The {@link org.apache.juneau.rest.StreamResource} class is the binary equivalent to the {@link org.apache.juneau.rest.ReaderResource} object.
In essence, it's a container for binary data with optional response headers.

The {@link org.apache.juneau.rest.StreamResource} class implements the {@link org.apache.juneau.Streamable} interface which is handled by the {@link org.apache.juneau.rest.response.StreamableHandler} class.
This allows these objects to be returned as responses by REST methods.

Example:

@RestMethod(...) public Object showPicture(RestRequest req) { // Return a stream resource loaded from a file. return StreamResource.create() .contents(new File("mypicture.png")) .header("Cache-Control", "no-cache") .mediaType(IMAGE_PNG) .build(); }

The important methods on this class are:

• {@link org.apache.juneau.rest.StreamResourceBuilder}
  • {@link org.apache.juneau.rest.StreamResourceBuilder#contents(Object...) contents(Object...)}
  • {@link org.apache.juneau.rest.StreamResourceBuilder#header(String,Object) header(String,Object)}
  • {@link org.apache.juneau.rest.StreamResourceBuilder#mediaType(MediaType) mediaType(MediaType)}

The {@link org.apache.juneau.rest.Redirect} object is a convenience shortcut for performing HTTP 302 redirects.

Redirect objects are handled by the {@link org.apache.juneau.rest.response.RedirectHandler} class.
This allows these objects to be returned as responses by REST methods.

The following example shows the difference between handling redirects via RestResponse and the simplified approach of using this class.

Example:

// Redirect to "/contextPath/servletPath/foobar" // Using RestRequest/RestResponse @RestMethod(...) public void redirectExample1(RestRequest req, RestResponse res) throws IOException { res.sendRedirect(req.getServletURI() + "/foobar"); } // Using Redirect @RestMethod(...) public Redirect redirectExample2() { return new Redirect("foobar"); }

The constructor can use a MessageFormat-style pattern with multiple arguments.

Example:

@RestMethod(...) public Redirect redirectExample3() { return new Redirect("foo/{0}/bar/{1}", id1, id2); }

The arguments are automatically URL-encoded.

Redirecting to the servlet root can be accomplished by simply using the no-arg constructor.

Example:

// Simply redirect to the servlet root. // Equivalent to res.sendRedirect(req.getServletURI()). @RestMethod(...) public Redirect redirectExample4() { return new Redirect(); }

{@link org.apache.juneau.rest.RestMatcher RestMatchers} are used to allow multiple Java methods to be tied to the same HTTP method and path, but differentiated by some request attribute such as a specific header value.

Example:

// GET method that gets invoked for administrators @RestMethod(name=GET, path="/*", matchers=IsAdminMatcher.class) public Object doGetForAdmin() { ... } // GET method that gets invoked for everyone else @RestMethod(name=GET, path="/*") public Object doGetForEveryoneElse() { ... }

The interface for matchers is simple:

public class IsAdminMatcher extends RestMatcher { @Override /* RestMatcher */ public boolean matches(RestRequest req) { return req.isUserInRole("ADMINS_GROUP"); } }

Notes:

• If no methods are found with a matching matcher, a 412 Precondition Failed status is returned.
• If multiple matchers are specified on the same method, ONLY ONE matcher needs to match for the method to be invoked.
• Note that you CANNOT define identical paths on different methods UNLESS you use matchers.
  That includes paths that are only different in variable names (e.g. "/foo/{bar}" and "/foo/{baz}").
  If you try to do so, a ServletException will be thrown on startup.
• Methods with matchers take precedence over methods without.
  Otherwise, methods are attempted in the order they appear in the class.

See Also:

• {@link org.apache.juneau.rest.annotation.RestMethod#matchers}
• {@link org.apache.juneau.rest.matchers.MultipartFormDataMatcher}
• {@link org.apache.juneau.rest.matchers.UrlEncodedFormMatcher}

The best way to handle a form post is by using an input bean.
The samples include a UrlEncodedFormResource class that takes in URL-Encoded form post of the form "aString=foo&aNumber=123&aDate=2001-07-04T15:30:45Z".
The code is shown here:

@RestResource( path="/urlEncodedForm" ) public class UrlEncodedFormResource extends BasicRestServlet { /** POST request handler */ @RestMethod(name=POST, path="/") public Object doPost(@Body FormInputBean input) throws Exception { // Just mirror back the request return input; } public static class FormInputBean { public String aString; public int aNumber; @BeanProperty(pojoSwaps=CalendarSwap.ISO8601DT.class) public Calendar aDate; } }

Another possibility is to access the form parameters individually:

/** POST request handler */ @RestMethod(name=POST, path="/") public Object doPost(@FormData("aString") String aString, @FormData("aNumber") int aNumber, @FormData("aDate") Calendar aDate) throws Exception { ... }

The advantage to the form input bean is that it can handle any of the parsable types (e.g. JSON, XML...) in addition to URL-Encoding.
The latter approach only supports URL-Encoding.

• If you're using form input beans, DO NOT use the @FormData attribute or {@link org.apache.juneau.rest.RestRequest#getParameter(String)} method since this will cause the underlying JEE servlet to parse the HTTP body as a form post.
  Your input bean will end up being null since there won't be any content left after the servlet has parsed the body of the request.
  This applies to WHENEVER you use @Body or {@link org.apache.juneau.rest.RestRequest#getBody()}

The Juneau framework does not natively support multipart form posts.
However, it can be done in conjunction with the Apache Commons File Upload library.

The samples include a TempDirResource class that uses the File Upload library to allow files to be uploaded as multipart form posts.

Example:

@RestResource( path="/tempDir" ) public class TempDirResource extends DirectoryResource { /** * [POST /upload] - Upload a file as a multipart form post. * Shows how to use the Apache Commons ServletFileUpload class for handling multi-part form posts. */ @RestMethod(name=POST, path="/upload", matchers=TempDirResource.MultipartFormDataMatcher.class) public Redirect uploadFile(RestRequest req) throws Exception { ServletFileUpload upload = new ServletFileUpload(); FileItemIterator iter = upload.getItemIterator(req); while (iter.hasNext()) { FileItemStream item = iter.next(); if (item.getFieldName().equals("contents")) { File f = new File(getRootDir(), item.getName()); IOPipe.create(item.openStream(), new FileOutputStream(f)).closeOut().run(); } } return new Redirect(); // Redirect to the servlet root. } /** Causes a 404 if POST isn't multipart/form-data */ public static class MultipartFormDataMatcher extends RestMatcher { @Override /* RestMatcher */ public boolean matches(RestRequest req) { String contentType = req.getContentType(); return contentType != null && contentType.startsWith("multipart/form-data"); } }

The {@link org.apache.juneau.rest.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:

• {@link org.apache.juneau.rest.RestInfoProvider}
  • {@link org.apache.juneau.rest.RestInfoProvider#getSwagger(RestRequest) getSwagger(RestRequest)}
  • {@link org.apache.juneau.rest.RestInfoProvider#getSiteName(RestRequest) getSiteName(RestRequest)}
  • {@link org.apache.juneau.rest.RestInfoProvider#getTitle(RestRequest) getTitle(RestRequest)}
  • {@link org.apache.juneau.rest.RestInfoProvider#getDescription(RestRequest) getDescription(RestRequest)}
  • {@link org.apache.juneau.rest.RestInfoProvider#getMethodSummary(Method,RestRequest) getMethodSummary(Method,RestRequest)}
  • {@link org.apache.juneau.rest.RestInfoProvider#getMethodDescription(Method,RestRequest) getMethodDescription(Method,RestRequest)}

The info provider in turn supplies the information returned by the following methods:

• {@link org.apache.juneau.rest.RestRequest}
  • {@link org.apache.juneau.rest.RestRequest#getSwagger() getSwagger()}
  • {@link org.apache.juneau.rest.RestRequest#getSiteName() getSiteName()}
  • {@link org.apache.juneau.rest.RestRequest#getResourceTitle() getResourceTitle()}
  • {@link org.apache.juneau.rest.RestRequest#getResourceDescription() getResourceDescription()}
  • {@link org.apache.juneau.rest.RestRequest#getMethodSummary() getMethodSummary()}
  • {@link org.apache.juneau.rest.RestRequest#getMethodDescription() getMethodDescription()}

Info providers are registered through the following property:

• {@link org.apache.juneau.rest.RestContext#REST_infoProvider}

While you can implement this interface from scratch, you may want to instead consider extending from the BasicRestInfoProvider class described next.

The {@link org.apache.juneau.rest.BasicRestInfoProvider} class is the default implementation of the {@link org.apache.juneau.rest.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.

In addition to the methods defined on the RestInfoProvider interface, it also includes the following methods:

• {@link org.apache.juneau.rest.BasicRestInfoProvider} implements {@link org.apache.juneau.rest.RestInfoProvider}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getVersion(RestRequest) getVersion(RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getContact(RestRequest) getContact(RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getConsumes(RestRequest) getConsumes(RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getProduces(RestRequest) getProduces(RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getLicense(RestRequest) getLicense(RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getTags(RestRequest) getTags(RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getTermsOfService(RestRequest) getTermsOfService(RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getExternalDocs(RestRequest) getExternalDocs(RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodSummary(Method,RestRequest) getMethodSummary(Method,RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodDescription(Method,RestRequest) getMethodDescription(Method,RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodOperationId(Method,RestRequest) getMethodOperationId(Method,RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodConsumes(Method,RestRequest) getMethodConsumes(Method,RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodProduces(Method,RestRequest) getMethodProduces(Method,RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodParameters(Method,RestRequest) getMethodParameters(Method,RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodResponses(Method,RestRequest) getMethodResponses(Method,RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodTags(Method,RestRequest) getMethodTags(Method,RestRequest)}
  • {@link org.apache.juneau.rest.BasicRestInfoProvider#getSwaggerFromFile(RestRequest) getSwaggerFromFile(RestRequest)}

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 {@link org.apache.juneau.rest.annotation.ResourceSwagger @ResourceSwagger} and {@link org.apache.juneau.rest.annotation.MethodSwagger @MethodSwagger} annotations on your resource classes and methods.
  

  Example:

  @RestMethod( swagger=@MethodSwagger(tags="foo,bar,baz") ) public Object myMethod() {...}

• Use properties files identified by the {@link org.apache.juneau.rest.annotation.RestResource#messages @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 MyRestInfoProvider extends 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 {...}

The {@link org.apache.juneau.rest.widget.Widget} class allows you to add arbitrary HTML, CSS, and Javascript to HTML pages.
They are registered in the following locations:

• {@link org.apache.juneau.rest.annotation.HtmlDoc#widgets() @HtmlDoc.widgets}
• {@link org.apache.juneau.rest.RestContextBuilder#widgets(Class...)}
• {@link org.apache.juneau.rest.RestContextBuilder#widgets(Widget...)}
• {@link org.apache.juneau.rest.RestContext#REST_widgets}

Example:

@RestMethod( widgets={ MyWidget.class } htmldoc=@HtmlDoc( navlinks={ "$W{MyWidget}" }, aside={ "Check out this widget: $W{MyWidget}" } ) )

The Widget class is composed of the following methods:

• {@link org.apache.juneau.rest.widget.Widget}
  • {@link org.apache.juneau.rest.widget.Widget#getHtml(RestRequest) getHtml(RestRequest)}
  • {@link org.apache.juneau.rest.widget.Widget#getStyle(RestRequest) getStyle(RestRequest)}
  • {@link org.apache.juneau.rest.widget.Widget#getScript(RestRequest) getScript(RestRequest)}

The HTML content returned by the {@link org.apache.juneau.rest.widget.Widget#getHtml(RestRequest) getHtml(RestRequest)} method is added wherever the "$W{...}" variable is used.

The CSS returned by {@link org.apache.juneau.rest.widget.Widget#getScript(RestRequest) getScript(RestRequest)} is added to the style section in the page header.

The Javascript returned by {@link org.apache.juneau.rest.widget.Widget#getScript(RestRequest) 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 {@link org.apache.juneau.rest.annotation.RestResource#staticFiles() @RestResource.staticFiles()}):

public class MyWidget extends Widget { @Override /* Widget */ public String getHtml(RestRequest req) throws Exception { UriResolver r = req.getUriResolver(); // API used for resolving URIs. return "<img class='myimage' onclick='myalert(this)' src='"+r.resolve("servlet:/htdocs/myimage.png")+"'>"; } @Override /* Widget */ public String getScript(RestRequest req) throws Exception { return "" + "\n function myalert(imageElement) {" + "\n alert('cool!');" + "\n }"; } @Override /* Widget */ public String getStyle(RestRequest req) throws Exception { return "" + "\n .myimage {" + "\n border: 10px solid red;" + "\n }"; } }

The Widget class also defines the following two convenience methods for loading Javascript and CSS files from the classpath or file system.

• {@link org.apache.juneau.rest.widget.Widget}
  • {@link org.apache.juneau.rest.widget.Widget#getClasspathResourceAsString(String) getClasspathResourceAsString(String)}
  • {@link org.apache.juneau.rest.widget.Widget#getClasspathResourceAsString(String,Locale) getClasspathResourceAsString(String,Locale)}

Example:

public class MyWidget extends Widget { ... @Override /* Widget */ public String getScript(RestRequest req) throws Exception { return getClasspathResourceAsString("MyWidget.js"); } @Override /* Widget */ public String getStyle(RestRequest req) throws Exception { return getClasspathResourceAsString("MyWidget.css"); } }

See Also:

• {@link org.apache.juneau.rest.RestContext#REST_widgets}

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:

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 {@link org.apache.juneau.rest.BasicRestServlet} class:

@RestResource( ... htmldoc=@HtmlDoc( header={ "<h1>$R{resourceTitle}</h1>", "<h2>$R{methodSummary,resourceDescription}</h2>", "<a href='http://juneau.apache.org'>" +"<img src='$U{servlet:/htdocs/juneau.png}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/>" +"</a>" }, head={ // Browser tab icon. "<link rel='icon' href='$U{servlet:/htdocs/juneau.png}'/>" } ), staticFiles={"htdocs:htdocs"} ) public abstract class BasicRestServlet extends RestServlet {...}

The "juneau.png" image file is located in 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 "$U{servlet:/htdocs/juneau.png}".

To change this image, you can extend the BasicRestServlet class and simply override the annotations pointing to your own icon.

@RestResource( ... htmldoc=@HtmlDoc( header={ "<h1>$R{resourceTitle}</h1>", "<h2>$R{methodSummary,resourceDescription}</h2>", "<a href='http://my.project.org'>" +"<img src='$U{servlet:/my-htdocs/my-project.png}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/>" +"</a>" }, head={ // Browser tab icon. "<link rel='icon' href='$U{servlet:/my-htdocs/my-project.png}'/>" } ), staticFiles={"my-htdocs:my-htdocs"} ) public class MyResourceBaseClass extends BasicRestServlet {...}

The footer icon shown is generated by a predefined widget:

@RestResource( htmldoc=@HtmlDoc( widgets={ PoweredByApache.class }, footer="$W{PoweredByApache}" ), ... ) public class RootResources extends RestServletJenaGroup {...}

The widget definition is shown below:

public class PoweredByApache extends Widget { /** * Returns an Apache image tag hyperlinked to "http://apache.org" */ @Override /* Widget */ public String getHtml(RestRequest req) throws Exception { UriResolver r = req.getUriResolver(); return "<a href='http://apache.org'><img style='float:right;padding-right:20px;height:32px' src='"+r.resolve("servlet:/htdocs/asf.png")+"'>"; } }

To provide your own footer icon, simply define it in your own footer section:

@RestResource( htmldoc=@HtmlDoc( footer="<img style='float:right;padding-right:20px;height:32px' src='$U{servlet:/my-htdocs/my-project.png}'>" ), staticFiles={"my-htdocs:my-htdocs"} ... ) public class MyResourceBaseClass extends BasicRestServlet {...}

Note how the "User Interface" is open-ended to pretty much lets you do whatever you want.

The sample root page renders in the default "devops" look-and-feel:

The sample root page provides a dropdown widget to try out the other default look-and-feels:

For example, the "light" look-and-feel:

And the "dark" look-and-feel:

The stylesheet URL is controlled by the {@link org.apache.juneau.rest.annotation.HtmlDoc#stylesheet() @HtmlDoc.stylesheet()} annotation.
The {@link org.apache.juneau.rest.BasicRestServlet} class defines the stylesheet served up as a static file:

@RestResource( htmldoc=@HtmlDoc( stylesheet="$C{REST/stylesheet,servlet:/styles/devops.css}", ), staticFiles={"styles:styles"} ) public abstract class BasicRestServlet extends RestServlet {...}

The "$C{REST/stylesheet,servlet:/styles/devops.css}" variable says to use the URI defined in your servlet's config file, if there is one, and to default to serving up the file org/apache/juneau/rest/styles/devops.css.

To provide your own stylesheet, simply override the stylesheet attribute and point to a different file:

@RestResource( htmldoc=@HtmlDoc( stylesheet="servlet:/my-styles/my-style.css}", ), staticFiles={"my-styles:my-styles"} ) public class MyResourceBaseClass extends BasicRestServlet {...}

You can try out different stylesheets by passing in a stylesheet attribute in the request URL.
The example above show this in use.

In case you're curious about how the menu item works, it's defined via a widget:

@RestResource( htmldoc=@HtmlDoc( widgets={ PoweredByApache.class, ContentTypeMenuItem.class, StyleMenuItem.class }, navlinks={ "options: ?method=OPTIONS", "$W{ContentTypeMenuItem}", "$W{StyleMenuItem}", "source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java" }, ) public class RootResources extends RestServletJenaGroup {...}

The StyleMenuItem is a widget that extends from {@link org.apache.juneau.rest.widget.MenuItemWidget}, a specialized widget for creating pop-up menus.
In the case of StyleMenuItem, it's simply returning a list of links wrapped in a div tag:

import static org.apache.juneau.dto.html5.HtmlBuilder.*; public class StyleMenuItem extends MenuItemWidget { private static final String[] BUILT_IN_STYLES = {"devops", "light", "original", "dark"}; @Override /* Widget */ public String getLabel(RestRequest req) { return "styles"; } @Override /* MenuItemWidget */ public Div getContent(RestRequest req) throws Exception { Div div = div(); for (String s : BUILT_IN_STYLES) { java.net.URI uri = req.getUri(true, new AMap<String,String>().append("stylesheet", "styles/"+s+".css")); div.children(a(uri, s), br()); } return div; } }