Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


ci Release Maven Central Javadocs

Easy conversion of HTTP payloads (JSON, XML, etc.) for Java.

Payload acts as a Java-to-<MediaTypeAsString> facade or abstraction for various libraries such as Gson, Jackson, JAXB and more. The underlying library used is known as the Provider and it gets evaluated in runtime by classpath lookup.

Conceptually similar to what SLF4J does for logging.

How to use it

import static com.juliaaano.payload.MediaType.*;

class MyObject {
  String value = "abc";
  MyObject() {
    // no-args constructor

/* Serialization */

Payload<MyObject> jsonPayload = JSON.payload().newInstance(new MyObject());
String json = jsonPayload.raw();
// ==> json is {"value":"abc"}

Payload<MyObject> xmlPayload = XML.payload().newInstance(new MyObject());
String xml = xmlPayload.raw();
// ==> xml is <MyObject><value>abc</value></MyObject>

/* Deserialization */

Payload<MyObject> payload_1 = JSON.payload().newInstance(json, MyObject.class);
MyObject obj_1 = payload_1.get();

Payload<MyObject>  payload_2 = XML.payload().newInstance(xml, MyObject.class);
MyObject obj_2 = payload_2.get();

Build and install

Payload does not bring any transitive dependencies, however it is required to deliberately have at least one of the pre defined providers in the classpath. You can also implement your own.



In case you just need JSON conversion, add Google Gson or any of the other JSON pre defined providers.



This library does not do any (de)serialization itself. It depends on finding in the classpath one of the following:


In case one or more are to be found, the priority is given by the order listed above.


It is possible to determine the priority of which providers are loaded. For example, if Gson and Jackson are present in the classpath, Payload can be configured to use Jackson instead of Gson by default.

All required is to include a file named in the root of the classpath:

Custom Provider
  1. Implement one of the available <MediaType>
  2. Declare the full name of your implementation class in a file as per java.util.ServiceLoader specification /META-INF/services/com.juliaaano.payload.json.<MediaType>ProviderFactory
package com.your.project;
public class MyProvider implements JsonProviderFactory {
  public Optional<Provider> newInstance() {
    return Optional.of(new Provider() {
      public String serialize(Object object) {
        return "your way to serialize";
      public <T> T deserialize(String raw, Class<T> type) {
        return null; // your way to deserialize

Further Details

Requires Java 8.