RealmTypeSafeQuery-Android

A type safe way to handle realm queries in Android.

Supports Realm query API 110% (there are some bonus features too 😉)

There are two big issues when working with Realm Queries.

1. If a field name is spelled incorrectly it fails at runtime instead of compile time.
2. If an argument is an incorrect type (Date instead of String) then the query fails at runtime instead of compile time.

If you have typesafe query parameters that allows you to refactor your models without worry of breaking your queries. All the field descriptors are auto generated using annotation process so you can't make a mistake. If you do, then it is caught at compile time and your app won't compile until you fix it.

Here is some java code highlighting what the API looks like

// Bad, field name and type are checked at runtime. This is using Realm the default way.realm.where(Person.class).equalTo("firstName", "Sally").findFirst();
// Better, field name is checked at compile time, but type is still at runtime.realm.where(Person.class).equalTo(PersonFieldNames.FIRST_NAME, "Sally").findFirst();
// Best, field name and type are both check at compile type.RealmTypeSafeQuery.with(realm).where(Person.class).equalTo(PersonFields.FIRST_NAME, "Sally").findFirst();

How to include JavaOnly project

In your top level build file, add the jitpack repository along with realm

buildscript {
dependencies {
classpath "io.realm:realm-gradle-plugin:5.0.1"// supported version of realm
}
}
allprojects {
repositories {
jcenter()
google()
maven { url "https://jitpack.io" } // RTSQ is hosted on jitpack
}
}

App module build file dependencies:

apply plugin: 'realm-android'// realm setup at top of file
android { ...[elided]...
// requires java 8
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
...[elided]...
}
dependencies {
...[elided]...
compileOnly "com.github.quarkworks.RealmTypeSafeQuery-Android:annotations:$RTSQ_version"// annotations
annotationProcessor "com.github.quarkworks.RealmTypeSafeQuery-Android:annotationprocessor:$RTSQ_version"// annotation processor
implementation "com.github.quarkworks.RealmTypeSafeQuery-Android:query:$RTSQ_version"// query dsl...[elided]...
}

Example Model

@GenerateRealmFields// Generates a file called PersonFields.java. This is a RTSQ annotation.@GenerateRealmFieldNames// Generates a file called PersonFieldNames.java This is a RTSQ annotation.classPersonextendsRealmObject {
StringfirstName;
StringlastName;
Datebirthday;
RealmList<Pet> pets;
// If what pops out of the code generator doesn't compile add these annotations.// Realm constantly updates their api and RTSQ might be a little behind.@SkipGenerationOfRealmFieldName@SkipGenerationOfRealmFieldRealmList<String> website;
}
@GenerateRealmFields// Generates a file called PetFields.java.@GenerateRealmFieldNames// Generates a file called PetFieldNames.java.classPetextendsRealmObject {
Stringname;
Integerweight;
}

Example Queries

finalRealmrealm = ...
RealmResults<Person> sallyNotSmiths = RealmTypeSafeQuery.with(realm).where(Person.class)
.equalTo(PersonFields.FIRST_NAME, "Sally")
.notEqualTo(PersonFields.LAST_NAME, "Smith", Case.INSENSITIVE)
.lessThan(PersonFields.BIRTHDAY, newDate())
.findAllSorted(PersonFields.BIRTHDAY, Sort.ASCENDING);
//Link queries also work tooRealmResults<Person> peopleWithHeavyPets = RealmTypeSafeQuery.with(realm).where(Person.class)
.greaterThan(PersonFields.PETS.link(PetFields.WEIGHT), 9000).findAll();

How to include KotlinOnly project

In your top level build file, add the jitpack repository along with realm

buildscript {
dependencies {
classpath "io.realm:realm-gradle-plugin:5.0.1"// supported version of realm
}
}
allprojects {
repositories {
jcenter()
google()
maven { url "https://jitpack.io" } // RTSQ is hosted on jitpack
}
}

App module build file dependencies:

apply plugin: 'kotlin-android'
apply plugin: 'kotlin-kapt'
apply plugin: 'realm-android'// realm setup at top of file but below 'kotlin-kapt' 
android { ...[elided]...
// requires java 8 (android build issue)
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
...[elided]...
}
dependencies {
...[elided]...
compileOnly "com.github.quarkworks.RealmTypeSafeQuery-Android:annotations:$RTSQ_version"// annotations// use kapt not annotationProcessor
kapt "com.github.quarkworks.RealmTypeSafeQuery-Android:annotationprocessor:$RTSQ_version"// annotation processor
implementation "com.github.quarkworks.RealmTypeSafeQuery-Android:query:$RTSQ_version"// query dsl...[elided]...
}

Example Model

@GenerateRealmFields // Generates a file called PersonFields.java. This is a RTSQ annotation.
@GenerateRealmFieldNames // Generates a file called PersonFieldNames.java This is a RTSQ annotation.// Kotlin classes are final by default (notice open)openclassPerson : RealmObject() {
var firstName:String?=nullvar lastName:String?=nullvar birthday:Date?=nullvar pets:RealmList<Pet>?=null// If what pops out of the code generator doesn't compile add these annotations.// Realm constantly updates their api and RTSQ might be a little behind.
@SkipGenerationOfRealmFieldName
@SkipGenerationOfRealmField
var website:RealmList<String>?=null
}
@GenerateRealmFields // Generates a file called PetFields.java.
@GenerateRealmFieldNames // Generates a file called PetFieldNames.java.openclassPet : RealmObject() {
var name:String?=nullvar weight:Int?=null
}

Example Queries

Realm.init(this.applicationContext)
Realm.getDefaultInstance().use { realm ->
realm.executeTransaction { realm ->val sallyNotSmiths =RealmTypeSafeQuery.with(realm).where(Person::class.java)
.equalTo(PersonFields.FIRST_NAME, "Sally")
.notEqualTo(PersonFields.LAST_NAME, "Smith", Case.INSENSITIVE)
.lessThan(PersonFields.BIRTHDAY, Date())
.findAllSorted(PersonFields.BIRTHDAY, Sort.ASCENDING)
//Link queries also work tooval peopleWithHeavyPets =RealmTypeSafeQuery.with(realm).where(Person::class.java)
.greaterThan(PersonFields.PETS.link(PetFields.WEIGHT), 9000).findAll()
}
}