@SerializedName annotation for defining Class/Field names

[beeender]

We need something similar to GSON's SerializedName annotation which can map a different name field from JSON string to RealmObject's property.

eg:

{ "dog_name": "abc"}

class Dog {
    @SerializedName("dog_name")
    private String name;
}

[navjotbedi]

Any update on this feature ?

[taltstidl]

I'd really like to use Realms Json methods, but the way they currently work they are unfortunately too limited to be of any use to me. In addition to a @SerializedName annotation, I'd also need a @SerializedObjectId(s)Name annotation that allows linking of related objects using their ids. Most web APIs only return the id of the related object, which makes it impossible to use Realms Json methods (as far as I know).

So, for example, the following should work:

{"id": 1, "relatedId": 1, "relatedIds": [1, 2, 3]}

class TestObject extends RealmObject {
    // different serialized name in json representation
    @SerializedName("id") @PrimaryKey
    long mId;

    // one-to-one relationship in json representation
    @SerializedObjectIdName("relatedId")
    RelatedObject mRelatedObject;

    // one-to-many relationship in json representation
    @SerializedObjectIdsName("relatedIds")
    RealmList<RelatedObject> mRelatedObjects;
}

Using those annotations the Realm Json methods should be able to properly transfer the information encoded in the Json to the Realm object model, including its relationships. Having those annotations would solve quite a few issues for me with partially updating objects (see issue #3500) and would reduce the amount of code needed and make it more efficient.

[cmelchior]

@TR4Android I have browsed through the code and compiled a list of things that needs to be done (I probably forgot something though). If you decide to start on this, I would strongly encourage you to open a PR as soon as possible so we can follow progress along the way and adjust if needed. It would make sense for us to make a feature branch which you can make smaller PR's against instead of trying to cram everything into one big PR against master. It will be a lot easier for us to review.

Let me know. Cheers.

Overall design goal

Make it possible to use a Java specific name when instead of being forced to adopt the name being used by a JSON API or another platform.

USE CASE: My JSON input does not match my preferred Java class. This is useful if using our various createFromJson methods

USE CASE: I'm sharing a schema with iOS and would like my own names as the chosen names break normal Java conventions.

With this approach we combine these two use cases. Is that okay or will it bite us later so we don't want to mix JSON and Schema concerns?

TODO List:

• New annotation : @SerializedName (let the bikeshedding commence). It is an apt name, but already used by GSON, I don't really know if Jackson/Moshi has something similar and what their concepts are called. The annotation can be applied to both classes and fields.
• Our Proxy classes need to use the serialized name when reporting its name.
• Our Proxy classes need to use @SerializedName instead of the field name when creating the ColumnInfo. This will probably require extending ClassMetaData with this information somehow, so the RealmProxyClassGenerator can output the serialized name correctly. See https://github.com/realm/realm-java/blob/master/realm/realm-annotations-processor/src/main/java/io/realm/processor/ClassMetaData.java#L55 and https://github.com/realm/realm-java/blob/master/realm/realm-annotations-processor/src/test/resources/io/realm/AllTypesRealmProxy.java#L48
• DynamicRealmObject: We need to figure out if DynamicRealmObject uses the serialized name or the Java field name when accessing fields. I'm leaning towards using the SerializedName name since that is the underlying object being exposed + the Java object might not be present
• RealmQuery: Should use serialized name for DynamicRealm and Java names for Realm. This really irks me, but I think it is the sanest option. Thoughts?
• RealmObjectSchema methods should operate on the serialized name, always.
• RealmSchema methods should operate on the serialized name, always
• Migrations should only be triggered if the serialized name changes. If the Proxy class is changed correctly I believe this will happen automatically.
• Add unit tests for making sure that serialized name works for all JSON methods
• Add unit tests for migrations being triggered correctly if SerializedName changes for both class and fields
• Add unit tests for queries on models with serialized names defined (both Realm/DynamicRealm)

Conclussion

Am I missing something on this list @realm/java and do you have other points? I believe @zaki50 and @kneth were the last to touch these parts of the code.

[Zhuinden]

I don't think JSON concerns should be mixed with schema concerns.

[cmelchior]

I have the same feeling, but it gets a bit tricky, because cross-platform schemas are a big topic for us right now 😄

public class Foo extends RealmObject {

  // This is definitely eecky
  @SerializedName("my_stupid_json_name")
  @FieldName("internal_name")
  private String name;
} 

Thinking about this. Maybe this is actually the best time to actually split our JSON API away from Realm, because a @SerializedName for JSON would only make sense if you used our JSON API, if you use e.g GSON it would just be confusing that Realm also had a similar annotation.

Instead we should create adapters for the various JSON imports:

- `io.realm:android-json-adapter:1.0.0` : Basically our existing API just moved to a seperate dependency. This library could then include specialized annotations like `@SerializedName`

- `io.realm:gson-adapter:1.0.0` : GSON type adapters

- `io.realm:android-streaming-json-adapter:1.0.0` : Our API 11 streaming adapters

Alternatively they get configured through the new realm closure block introduced in 2.0

It would have the following implications:

• All createFromJson* and createOrUpdateFromJson* methods would be removed from our current public API.
• JSON Support is entirely opt-in. Right now they are a massive chunck of our proxy classes, we could strip a lot of code.
• We will have to find another way of calling JSON methods. GSON/Moshi/Jackson can continue to use our copyToRealm, but we need somewhere to hook "standard" JSON output in. Where isn't clear to me.

[taltstidl]

@cmelchior I tend to agree with @Zhuinden, I wouldn't want to mix the field and json names. Splitting this to its own library might make sense, as it would allow room for more superior support without making the core library more cluttered. I'd gladly add export APIs to this as well. Might make sense to name this realm-import or similiar and have it available for more platforms.

I'll probably need some guidance on the implementation then. Should the supplementary library alter the proxy classes? How should I split the library from the core one? How should I name the new classes for importing/exporting json?

I'll definitely create a PR as soon as possible, so you can track progress and intervene when I make mistakes on my side. I'm already exited to see this in a future release as it will make my app code that much simpler, and hopefully more performant!

One other thing, for the annotation I'd like to be able to build links to other objects using its primary key. That is currently the main reason I'm not using other json libraries, as I'm looking to build the relationships more natively. So, I'd like to see an option for that in the API design as well (see my previous comment).

[Zhuinden]

@cmelchior considering additional annotation processors can be executed on the same RealmObjects now that annotations aren't consumed, adding additional adapters (or adapter factories akin to Retrofit2) would make sense similarly to how "Rx support" is opt-in by adding the RealmObservableFactory.

[cmelchior]

@TR4Android I didn't consider the possibility to automatically hook up references, but you are right, it would also be a nice feature if done automatically. Especially since it is a lot of tedious code to do manually.

Basically by splitting the library we don't have to be as conservative with features, so export capabilities also make a lot more sense. I would however expect we want to share a lot of code between annotation processors, so we would need to find a way to do that.

We probably need to have an internal discussion first though as there are a lot of moving parts to this, but if you have some good ideas for how the public API could look like for this I am all ears.

@Zhuinden Yes, not consuming the annotations is definitely a major part of this as this allow us to mix any number of adapters. While the Retrofit factory method is very nice, keep in mind that right now we accept 3 different forms of JSON Input: InputStream, String and JSONObject/Array, so I don't think we can get away with just having a factory method somewhere as those 3 types are basically 3 different adapters.

[taltstidl]

@cmelchior Yes, you should probably have an internal discussion first. I'm not sure yet how the structure of the annotation processor should look, this is something I'd first have to investigate more. Any ideas would be appreciated. The public API would be pretty much what I have outlined in the other issue.

[cmelchior]

I'm mostly talking about the createFromJson* methods and friends. With the adapter approach I don't think it would make sense if they hang on the Realm object anymore, but they need to be somewhere (wishes for Kotlin extension methods)