I'm Eric, I work on Android, open source things, Java libraries, and I'm going to be talking about Mashi. Who here has played with Mashi at all? Okay, cool. Who here has used Gson before?

Okay, cool. Yeah. So this is going to be a lot about less Mashi's API and more about how we step from Gson to Mashi and the niceties that Mashi has gained from learnings in Gson.

So what is Mashi? It's a JSON serialization library. It has both a streaming and an object mapping API. So you can stream things directly from the socket, you know, you're going you're pulling things off of the network, and then on top of that, it has your friendly abstraction

for mapping this data, all these bytes, into your Java data classes or value classes so that you can use them on the application layer in a friendly way.

Mashi is also a very compact, small library, and originally written by Scott, Jake and Jesse all at Square at the time a few years ago, and you might know Jesse Wilson from

writing basically everything, works a lot on okay HTTP, but importantly for this talk, he wrote a lot of Gson 2's API. So when I say upgrading to Mashi, it's not a slight on Gson in any way, it's very much that it's by the same authors with the same intent of providing a better interface

for Gson, and all the things that we learned in making Gson, and all the things that Gson 2's API really made handy for developers. So Mashi is kind of Gson 3, but I kind of think of it as Gson lite, it's a smaller

API, it is more opinionated about a lot of things, also importantly, it's built on okay IO, so okay IO is the bytes library that you use under the hood in okay HTTP,

and basically any kind of IO that you use, it's a lot better than Java.io. So why upgrade to Mashi, why now, why upgrade from Gson, Gson kind of works well

enough in a lot of places, and that's really true. The reason Mashi is not Gson 3 is none of the actual maintainers of Gson work at Google right now, although kind of funny enough Jake Wharton now does, but it's not really

being actively maintained, and basically Gson 3 just wouldn't happen. A lot of internal systems at Google and across probably all the companies we work at rely on Gson, and so it's not necessarily something you have to update, and it's

not something a lot of people will update, a lot of systems will update, so that's why it's not just purely Gson 3, it's a little bit of just the spiritual successor rather than direct correlation there.

So the biggest thing why you would update, or like why you might be able to tell your project manager or your engineering manager why you might update, Gson is not an active development. It's not because it's really a stable or a complete library, it's just really hit

the pace where it's not being actively, there are no active features developed, there's a lot of things that are kind of broken, but Gson 3 just can't happen, it doesn't have enough support for that, so it's just kind of slowed to a crawl, and really all

active development on Gson you'll really see in the moshy side. The thing that you as an implementer, as a developer are going to see much more is that Gson is really lenient.

You can do a lot of really not great things with Gson and it will just let it slide and it will be great until it doesn't work and then you'll be debugging into a bunch of the source code of Gson and have to figure out why that edge case didn't work. We're going to go over some of the examples where Gson is too lenient, but this is really

just across the library and things even like the default Boolean type adapter lets you actually have true and false as string literals rather than as Boolean literals. It lets enums just pass and then you'll get nulls when you have an unknown enum string

type, and it also lets you use platform, you get tied to platform types. You could use something like you could say Gson, can you deserialize this array list

for me and it will try to do it to the best of its ability and then you're really tied to that platform concrete type of array list and then your Android version updates and then now it's not going to work as you expect, so Gson is just too lenient there and you'll get subtle bugs.

Also it has a rather large API. It has a lot of things that aren't quite clear, they're order of precedence for when you have for when your type adapter will get called or created. It also has things like Gson deserializer and Gson serializer and it's not quite

clear when to use certain parts of the API and a lot of it is like baggage from Gson 1 and a lot of things will because it's not so clear can cause performance issues like if you're using Gson deserializer instead of the type adapter APIs then you'll

lose streaming support and you'll basically be buffering your entire objects at once rather than feeding it down the line. So Moshi aims to have a more opinionated API to prevent yourself from making mistakes and to encourage you to do the most efficient thing and performant thing.

One of the things that's been slightly improved in Gson is error handling, but it's still not great. You'll get they're kind of all over the place. You'll get IO exceptions in different places, again, and it's things where you'll have

to go in and debug the source of Gson to figure out where it's coming from. Moshi is pretty clear on exceptions. It throws a subclass of IO exception for when there's actually an IO exception. So when you've gone into a tunnel and you can't pull down any more of your of

those bytes then you just get an IO exception and then when there's actually a problem when you were expecting an integer but it was a string or the other way around you're going to get a friendly JSON data exception and be able to solve the problem more easily

there. So two of Moshi's goals are really to be really small, to be really performant so you can run it on Android, not just on your JVM, but also to make your life as a developer really easy so that you can sit down, you can read the API docs, you

can read the readme in 30 minutes and you know exactly what you need to do and it can just handle what exactly can handle your more complex use cases but again has that

focused API so that you can understand it readily and that's why I'm not really going to be going over a lot of the API because it would be a failure of Moshi if it weren't clear from the docs. And of course the other thing is very small.

Moshi is has significantly fewer methods than Gson but this is assuming you already have OKIO in your project because a lot of the heavy lifting is actually taken care of by OKIO and since modern Java developers are using things like OK HTTP we already

have OKIO in our projects. I don't expect this to be really like a game changer, really to be to push somebody over the edge to try Moshi but it's there, it's slightly smaller, those sizes are of the deck size that's added to your final binary.

And then I'm going to go over some of the big optimisations and API niceties of Moshi. I would say the API niceties are really the big thing. I'm going to talk about some actual performance optimisations but the API is what's really

going to save you a lot of effort in your time as a developer because I consider a lot of the performance to not be as big of a deal because most of the time when we're using things like Moshi we're using it on the network and a lot of the latency from the

network just overshadows the performance time of your actual serialisation library assuming that you're doing streaming and not buffering an entire model into memory. So the big, two big things. The first big thing in Moshi's optimisation handbag is saving buffer segments and it

works well with other OKIO users. So if you're using OKHDP and Retrofit this is really handy because you don't have to have multiple references to the same data because OKIO actually internally will

just share these buffer segments across users of OKIO statically. The second thing is that Moshi will avoid allocating strings while deserialising. So this is a big thing especially when you use reflection.

So the default adapters that you use when you're using Moshi or Gson are using reflection to set your fields and such, the values to your fields with your model objects. In Gson when you've got your data class and you've got some fields in it and then

Gson has to know about the names of those fields and so those are strings and then we have to allocate those strings when we're deserialising and then when we're done they have to be garbage collected. So there's a little bit of a performance hit there and it's a bigger deal when you've

got lists and you're just over and over allocating all these strings, throwing them away. Moshi does a smart thing that's actually an abstraction borrowed from OKIO which is an options API that we'll go over in a little bit but you basically pre-allocate these strings and then can just get the index of the string in the options data type

so that you're not, you basically pre-allocated these strings and you're not allocating them as you're streaming. So how to upgrade. So now we're going to be talking about going from Gson to Moshi like given those,

given that value proposition. The first thing or I think the plurality of people might notice is there's no field naming policy. Gson, this is something that I would say is just too lenient of an API, too awkward

of an API that Gson had. This was things like you could, most of your Gson, your server is saying OK it's snake case probably and then you as a Java developer go well I want it to be camel case

and then you tell Gson OK map all of my camel case things to, all my camel case fields to snake case automatically or kebab case, there are a few different field naming policies. Moshi doesn't have this and the reason is that it's awkward for maybe mainly just

searching so when your server developer goes in your code base and says OK I need to find the underscore name, now I can't find it and your server developer doesn't know

that you have this weird field naming policy that tells Gson internally to map your camel case to snake case so then he just doesn't find it across your code base and causes a lot of confusion, he has to contact you, et cetera.

Jesse wrote this almost two years ago on your field, your strict naming conventions are a liability. I encourage you to read it, I'll post the slides after the talk, there will be a lot of links and so he covers this and also it's just kind of a waste of computer

time to need to do this. And the bigger like more my opinion or more of an opinionated take on it is that I really think it's nice to stay in the domain of the language that you're using, so when

you have these Java models that are reflecting your Gson models, I actually think it's nice to stay in whatever your server says, if that's most of the time snake case. And we actually as Android developers do this all the time with XML, our XML layouts,

we normally give our view IDs, we do snake case, and even though we reference them in Java, we're not offended by that, we know we actually see it as an indication that

oh, I'm referencing something that belongs in XML. So this is kind of an approach I've taken, I actually just model my Java models, my Java data classes based on what the actual Gson naming is, and it's a signal to me as a developer, okay, this is a Gson model, this is what I'm talking about, it's

not my database model, it's not really my application model, it's exactly what my Gson says. So this doesn't mean that serialized name is gone, so a lot of the times you might have something that's called object, and so without some way of mapping that easily,

that would be a huge problem in Java, because we couldn't map our Gson name object to something, because it's a protected keyword in Java, so serialized names still exist, this solves the case for if you really need to use camel case, if it's a company policy, your check

style or something requires it, you can't use field naming policy, but you can go to every single field and still annotate it with at Gson, and so then the reflective class JSON adapter will look at at Gson and say, okay, this is the real name, don't use Java's

field name here, use the at Gson, so this is one of the things you'll change, if you use at serialized name in Gson, you've got to change that to at Gson for Mashi, that's the name of the annotation to use there.

So this is what I said, I personally prefer, I encourage other people to try it out, just use the domains naming convention as a reminder of what your data is actually talking about. So the streaming API, this might be a little bit lower level than maybe application developers

always deal with, but the good news is it's really the same, Gson actually has a really good API for streaming, the simple Json reader and Json writer are very similar in

Mashi, really just have to change your import statements, and you get all the nice read Boolean, begin object, end array, all those very high level function methods that we use from Gson. It also has a few nice additions, so we're going to talk again about the Json reader

options and also the set fail on unknown, the Json reader ads, those are the two I'd say biggest additions that the streaming API in Mashi has gained over Gson.

The Json reader options, again, prepare strings ahead of time, so you create an options, you just tell it, okay, these are like the keys, these are the keys for my Json object, these are the field names, and now we've just pre-allocated them once, and then we can read them right, and then we can read the options directly off the input source.

So there's the API. You can select name, this will just grab the next name, and then select string, similar. The result of this will return the index in the options.

So if the next name there in our stream is key one, then it will return zero. If it's key two, it will return one. If it's key three, it will return negative one. We don't have that thing, and you should probably skip the value.

Set fail on unknown, this is a really great debugging option. So this basically just tells the Json reader next time you try to call skip value, throw Json data exception, and you probably don't want this in production code, but when you're

writing out, when your server developer says I've got this new API, it's going to give you this data, and you need to show it on this screen or something, you can know that you're actually consuming all of the data that your server developer has given you. So if there's an extra field, you forgot to use the user's last name or something,

you're going to find out about it immediately. It's going to say, oh, I tried to skip this value, but really, you should have mapped this value to something. Okay, and then object mapping. This is more of what us application developers use. This is the higher level of abstraction where we actually use, we actually map our Json

to Java models. So the type adapter API is really good, and it's just been renamed for Mashi, it's just called Json adapter to distinguish itself. It doesn't have a, so Mashi doesn't have a documentation level API.

That might be one of the biggest things you first encounter. So the Json object and the Mashi object, these instances that we use, these are really holders, they're more like caches for our adapters.

So we have all of these type adapters, our string type adapter, maybe like my data adapter, and they hold caches for these adapters. But if it's a type adapter that you're really going to be using a lot, it's better that you actually cache it yourself. So there's, Mashi doesn't actually know anything about your document.

It just knows the reader that you give it, and it goes through until you finish consuming in the reader. So if you need to do any assertions that you've consumed the entire document, you need to do that more at the application layer. So there's not any Mashi dot from Json.

You're actually going to need to get the adapter. So Json had this API, get adapter. It's basically the same in Mashi, you get the adapter, and you should cache your adapters.

Again Jesse wrote another blog post about reflection machines. The Mashi's Json adapter and Json's type adapter are examples of reflection machines, and they have a factory API where you actually do the heavy lifting, and you need to do all of the up front work.

By default, Mashi uses a reflection for all of your custom classes to set all the fields. So you might think that that's expensive, but really all the hard work you need to do is up front, getting at all the fields, but actually binding to these fields is not

very expensive. So if you do it up front, and you keep around your instance of the adapter, then the work is already done just once when you're actually creating the adapter. And then when you're actually using it, when you're streaming your data, then it's

much less expensive. So that's the idea of a machine of knowing when to cache data just once. So object mapping without Json's bad leniency. Platform types require explicit Json adapters in Mashi.

So Json, like I mentioned, was really lenient about this. If you've ever developed kind of a maybe moderate to more complex application, you've probably run into Json's weird date formatting. So that's kind of a whole issue on its own.

But you could get tied down to Json's default date type adapter and then not really know the right way of approaching it to fix it. So instead, you have to supply explicit adapters.

There's an artifact in the Mashi repository for the common RFC 339, I think it is, date type. So that will cover most of your common use cases. But just know that you need to include that and be able to if you have date types in

your Json data. Also things like array list. This is kind of something I commonly saw in a lot of code that Json touched. Just use list most of the time.

But again, the reason we don't let you use array list or any platform type is you get tied down to the platform. Like there you could use an Android type and then you'd end up your Android version upgrades but you were relying on those implementation details of like the field names in point.

And then Android upgrades and then that no longer applies and you've just ruined all of your Json models. So if you need to do that, you need to use the public API of those types and supply a direct Json adapter for them.

So also, Mashi, this is very similar, Json had something pretty similar. Wrapping your Json adapters, similar type adapter had very similar things. Serialize nulls so that by default when you are serializing, if your field maps to

something that you just have a null value in, it just doesn't serialize that. But if you tell it to serialize nulls, it will actually have the field, have the key, and then the value will be the null literal in Json.

Null safe, so yeah, I love what it sounds like. Lean it. So again, by default, not lean it on a lot of things. Like if you have, but if your server is weird and maybe has a lot of weird HTML escaping or has missing quotation marks where it's supposed to, maybe for the keys in your

Json objects, you'll want lean it on your Json adapters. Indent, so this is basically again kind of a debugging feature. If you need to pretty print your things, you can add in like four spaces or add in a tab or something for the indents in pretty printing your Json.

Fail on unknown, we covered that. That's the new thing for Mashi, and so this just tells the Json adapter to temporarily make the Json reader fail on unknown, and then when the Json adapter is done with it, then go back to whatever the Json reader was using before.

So object mapping, the two things that you'll notice are missing are Json serializer and Json deserializer. These are APIs in Json that were not good.

Well, they're kind of baggage. They were easy for a lot of people to implement for their custom logic. But they didn't stream. So they were actually buffering your entire value at once in memory, and so you lose

all the performance benefits. And it's also just an added API, really hopefully you don't run into this, but the better thing that all new code should be written in is the type adapter API, and of course

in Mashi, the Json adapter API. So hopefully you're using type adapter and type adapter factory. These map basically one to one with Json adapter and Json adapter.factory in Mashi. The other thing is there's no more type token API, which is really nice.

You'll kind of see this as a pattern, too, in Mashi. Mashi tends to prefer normal Java types that you already know. So you actually just end up using the Java.lang.reflect type API more than type token.

And instead of the type token and having to subclass it and do kind of weird things, there's actually a types factory class in Mashi, it's a public API, and it has all sorts of niceties, again, not going to go over the whole API, but basically everything

you had in type token, you actually just use the types API to be able to just create normal Java types. So here's a common example. If you have a list of strings, you had to use the type token and then create a type token and then basically you had this type token type that only Json understood.

In Mashi, this will just return a normal Java.lang.reflect.type. There's another thing that's not quite 100% in Mashi that you maybe should be aware of

if you use enums in your Json. It definitely wasn't 100% in Json, but if you had an unknown type, so your enums, you say they're just strings, but at your application layer, you want to think about

them as enums, but in your Json, obviously they're just strings. But if you ran into an unknown string in Json, again, it was really lenient and it would just give you null. So you couldn't tell it to, there wasn't an easy API to tell it to give you a fallback

value or anything. It would just give you null. And that's not super great. It's a little bit awkward to have a null enum type. Normally, I'd say prefer just like adding another type for unknown or something. So the Json's API wasn't great there, but then in Mashi, if you have an unknown

type, it does the right thing for the common case. It does the right thing in that it throws a Json data exception. It says this was an enum, so it has to be strictly these values. I didn't find one of these strings in the Json.

I don't know what to do with it. Here's a Json data exception. But if you maybe don't control your server, your server team doesn't communicate to you all the time or something, that can be weird. Like maybe your server upgrades and then now you have a new type, it has a different string, and you don't want to fail your deserialization.

You don't want to fail the whole network request. You want a fallback type. Mashi doesn't have a great solution to this currently. So I've actually written an enum with default Json adapter implementation, which, again,

I'll post the slides and get the link. But I want to hear from kind of the community, there's an issue on Mashi on GitHub for it. I want to hear, like, plus one the issue, give feedback, give any comments if you have any idea. We're still kind of looking for what the right API might be to give this fallback.

But for now, I've written an implementation that basically copies out the enum Json adapter that's internal in Mashi. So the other thing is special casing type qualifiers. So in Json, we had this at Json adapter, not to be confused with Mashi's Json adapter,

that would tell it to special case this type, and it was kind of a type qualifier. The weird thing was the order of precedence for when this type adapter was going to be used isn't very clear.

Mashi solves this really cool, really well with Json qualifier annotations. And so you can actually have this type qualifier. So here we have, like, a wrap string, and then this is what it might have looked like in Json. You had to write all this.

And then in Mashi, here's what our wrapped Json qualifier thing might, Json adapter might look like. This is, you'll notice that this kind of varies from our type adapter implementation in Json, as it's just a normal Java object.

So that brings us to easier Json adapters exist in Mashi. So this is what a very formal Json adapter factory might look like when you have a custom type in or when you need to do something interesting with Mashi.

And so you have all of this logic, and you've got to remember, okay, if it's not this point, I need to tell it to continue on down the list of adapters, and then here's our actual meat. Well, Mashi makes this much easier. You can actually just feed it, you can just actually create normal objects and feed it

to the Mashi builder, and then reflectively it will actually create the proper factory for you. So adapters become much easier in Mashi, rather than its strict factories or Json's

type adapter factories. So, again, even easier Json adapters. We have things, you can create these from Json is the annotation. It doesn't do anything magic. It's not an annotation processor. It just tells Mashi when Mashi looks for the annotation reflectively on your method,

how to create the factory when you're building your Mashi builder. So it's really easy to add in delegates to create these more complex adapters.

Polymorphic types, this is something that's more of an advanced use case where you have something like animal, and based on this type field, we need to deserialize it differently. So you might have a dog that, again, has a string, but your cat has an integer, and

then we have a list of all these things coming down from our server, and we need to do different things based on what type they are. Json had, again, its own types for this. It had Json element, which could be a Json object, it could be a Json array, or basically

it could contain a Json object, it could contain a Json array, a string or primitives. Mashi just uses regular Java object, and that object could be a map, a list, a string or primitives, because those are all the things that your Json could be. So, when we get to these polymorphic types, this is what it looked like in Json.

You would read out the type in your Json, you have to get it as a Json object, and then in Json, you would get it as a Json tree to get the current thing and decide

which adapter to delegate to. In Mashi, there is this neat readJson value thing that buffers the entire value, similar to Json, but in just a Java map way, or a Java object way, there, we are telling it is a map, and then we say, okay, this is the value, delegate it to our cat adapter,

because the type was this cat. Json handles the common case with a runtime type adapter factory, Mashi doesn't really have an extra, like a sample API or design for this yet, so again, kind of looking

for community contributions or ideas on what the common use case for that is. Updating piecemeal, this is, again, something you can look at later, but the retrofit makes this really easy because it actually passes down these annotations to its converter factories,

so without getting into retrofits API, there is sample code, you can look at how it's implemented, but this is a really easy way of saying, okay, only new code you deserialise with Mashi, everything, all of my new end points should use Mashi, all of the other end points should fall back to Json, and a quick note, auto value Mashi exists, Ryan Harder works

on this, and others, and it's a basically really simple API, just remember to have this static method, even better, you can just have this abstract class, and this

will create a factory for all of the types that you've annotated with auto value, and then you just apply this to your Mashi builder, you apply it to your Mashi builder, and then it will use all of the correct adapters, and auto value Mashi also uses the select

name trick, so it uses the Json reader.options, API, again, for performance reasons, that's super cool, a few resources, this is Jesse's announcement blog post, talks about some of the advantages, talks about other places to go to see it, also, Jake's talk on a few

OK libraries, talks more about OKIO and its types, and also how it applies to Mashi, and how Mashi retrofit and OKHTP are all built on OKIO and are really strong together, also, I monitor Stack Overflow, Jesse also monitors Stack Overflow most of the time,

and so ask any questions there, we try to respond there, and also, you know, I'm on Twitter and most places, and feel free to ask questions, yeah, and so, contribute, one thing I would say is I didn't really mention Kotlin, a Kotlin Json adapter does

exist, so I didn't go over it, but if you're using Kotlin with your data classes, then Mashi is going to be a lot friendlier to you than Json.