[5] Cookbook

You'll find some optional andcouchbaseentity features here.

Model Validation

To make sure you don't mess up things in production by doing changes on existing models some kind of validation would be great, right?

andcouchbaseentity can generate a schema json file on every build and our andcouchbase-entity-versioning-plugin helps you to manage your different productive versions.

Lets see how to use it:

declare buildscript dependencies:

buildscript {

    ...
    ext {
        entity_version = "3.6.0"
    }
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
    dependencies {
        ...
        classpath "com.github.SchwarzIT.andcouchbaseentity:couchbase-entity-versioning-plugin:$entity_version"
        classpath "com.github.SchwarzIT.andcouchbaseentity:couchbase-entity-api:$entity_version"
    }
}

configure plugin and activate schema generation:

apply plugin: 'andcouchbase-entity-versioning-plugin'

def scheme_path = "${buildDir.absolutePath}/entity_schema"
def scheme_name = "my_schema.json"

import kaufland.com.coachbasebinderapi.schema.DefaultSchemaValidator

couchbaseEntityVersioning{
    currentSchema "${scheme_path}/${scheme_name}"
    // path where the plugin should add your schemas to check against
    versionedSchemaPath = "prod_schemas"
    // this is the default validator implementation you can change it by your own implementation if you want to.
    validationClazz = DefaultSchemaValidator.class
}

kapt {
    arguments {
        arg("entityframework.schema.generated", "$scheme_path")
        arg("entityframework.schema.fileName", "$scheme_name")
    }
}

Use it:

plugin commands:

validation:

gradle validateSchema

manage:

gradle addSchema -Pentity-version=X.X.X

gradle removeSchema -Pentity-version=X.X.X

ID Helper (DocId, DocIdSegment)

If your database using ids in documents you may find it useful to have some kind of factory method to generate them.

@Entity
@MapWrapper
@Fields(
        Field(name = "type", type = String::class, defaultValue = "product", readonly = true, comment = ["Document type"]),
        Field(name = "name", type = String::class, comment = ["contains the product name.", "and other infos"]),
        Field(name = "comments", type = UserComment::class, list = true, comment = ["I'm also comfortable with pseudo %2D placeholders"]),
        Field(name = "image", type = Blob::class),
        Field(name = "identifiers", type = String::class, list = true)
)
@DocId( "myProduct:%type%:%name%:%custom(name)%")
open class Product{

    companion object{
        @DocIdSegment
        fun custom(name : String?) : String = "${name}blub"
    }

}

A little plus this annotation is also included in the generated schema json which means you can validate if the pattern has changed.

Deprecated

If you support multiple versions of your clients you will come to the point where fields or whole documents become deprecated. By using the andcouchbaseentity deprecated annotation you get some nice gimmicks

• generated fields accessors become also deprecated
• by using attribute "inUse" you can define if this field is still in use. If not the resulting deprecation level becomes Error.
• schema validator is also aware of this annotation and the default validator allows only not in use fields/models to be removed.

@MapWrapper(modifierOpen = true)
@Fields(
        Field(name = "country", type = String::class),
        Field(name = "type", type = String::class, defaultValue = BaseArticle.TYPE, readonly = true),
        Field(name = "article_no", type = String::class),
        Field(name = "unit", type = Unit::class),
        Field(name = "other_units", type = Unit::class, list = true)
)
@Deprecated(replacedBy = NewArticle::class,  fields = [DeprecatedField(field = "unit", replacedBy = "new_unit")])
open class BaseArticle

Generate Suspend functions for database interactions

kapt {
    arguments {
        arg("useSuspend", "false")
    }
}

Generate Model documentation based on declared Entities/Mapwrappers

kapt {
    arguments {
        arg("entityframework.documentation.generated", "${buildDir.absolutePath}/entity") //path to generate documentation
        arg("entityframework.documentation.fileName", "demo.html") //optional name for the generated html file
    }
}