Entity Factory

• Getting Started
• Defining a Factory
• Using Factories
  • Creating and Persisting an Entity
  • Manually Saving an Entity
  • Overriding Entity's Blueprint Properties
• Creating Entities Using from Method

Transforming Values Before Persisting

An entity factory allows you to define a blueprint for an Ozone entity, which can then be used to make one or multiple copies of the entity. You can combine an entity factory with a seeder to easily populate your database with some quick dummy data.

Getting Started

A factory is simply a class, or preferably, an object, extending the abstract EntityFactory class. You are required to provide an instance of an Ozone table instance and must override entity() method. This method is where you would return an Ozone Entity instance.

The quickest way to create an entity factory is by using the make:factory Alpas console command. This command takes the name of the entity, or a list of entities for which the corresponding factory needs to be created. All the entity factories are conventionally kept under database/factories directory.

# Creates a factory for the Account entity
$ alpas make:factory Account

# Create multiple factories for multiple entitites
$ alpas make:factory Project Contact Post

internal object UserFactory : EntityFactory<User, Users> {
    override val table = Users
    
    override fun entity(): User {
        return User {
            name = faker.name().name()
            updatedAt = faker.date().past(1, TimeUnit.HOURS).toInstant()
            createdAt = Instant.now()
        }
    }
}

Defining a Factory

Usually, while defining the blueprint of an entity, you'd use some fake data. To make it easy to create some fake, dummy data, Alpas comes bundled with the Java Faker library and a global faker object is available for you to use inside your factories. You can create your faker instance if you need.

As mentioned before, the only method you are required to override in your concrete factory is the entity() method. From this method, just return an instance of the actual entity without actually persisting in the database as you may not always want to persist it in the database.

override fun entity(): User {
    // Don't persist; just return an instance!
    // Since User is an interface, notice how we are creating the instance
    return User {
        name = faker.name().name()
        email = faker.internet().emailAddress()
        updatedAt = faker.date().past(1, TimeUnit.HOURS).toInstant()
        createdAt = Instant.now()
    }
}

Feel free to fill all the properties of your entity in this method. You can override any properties later when you are actually calling this factory.

Using Factories

Since a factory is just an object instance (or a class), you can use it directly. There are few things you can do with a factory.

Creating and Persisting an Entity

The create() method is responsible for actually creating an instance of an entity from the blueprint and persist in the database. It also returns a fresh copy of the entity from the database to make sure all the relationship bindings are available on it, if any.

// This will create and save an entity record in the database
val user = UserFactory.create()

Manually Saving an Entity

If you just built an instance of an entity without persisting it, you can call the saveAndRefresh() method to save it to the database and return a fresh copy of it.

// This will only create a User instance without persisting in the database
val user = UserFactory.entity()

// This saves and then fetches a fresh copy
val freshUser = UserFactory.saveAndRefresh(user)

Overriding Entity's Blueprint Properties

Sometimes, for more controlled testing, you may want to use some specific data for some specific attributes, say for an email, instead of using some fake data.

The real power of a factory is in being able to override an entity's properties defined in the blueprint on the fly. Even if you have defined the blueprint completely with fake and random data, you can always override the values by passing a map of attributes to override when calling the factory.

// Create a User instance by overriding email and name fields that are defined in the blueprint
val user = UserFactory.create(mapOf("email" to "jane@example.com", "name" to "Jane Doe"))

// Build a new user by overriding some properties
val anotherUser = UserFactory.build(mapOf("name" to "Jane Doe"))
// This saves and then fetches a fresh copy
val refreshedUser = UserFactory.saveAndRefresh(anotherUser)

Creating Entities Using from Method

You can use a slightly convenient from() method to create one or multiple instances of an entity. This will persist the instances in the database. So, in a way, it is just a proxy for the create() method.

// Create a user instance, override the properties with values from
// the given map, persist the instance, and fetch a fresh copy of it.
val user = from(UserFactory, mapOf("name" to "Jane Doe"))

// Create 5 instances of the User entity.
val users = from(UserFactory, 5, mapOf("country" to "USA"))

While using from, you can also override the properties using strongly typed assignment builder:

// Create a user instance, override the properties with values from
// the given map, persist the instance, and fetch a fresh copy of it.
val user = from(UserFactory) {
    it.name to "Jane M. Doe"
    it.email to "differentjane@example.com"
}

Transforming Values Before Persisting

You can transform the value of an entity's property before saving it to database by overriding transform() method and returning a new value. This is useful, for an example, to hash a password before it gets saved in the database.

There are other ways you can achieve this but doing it inside the trasnsform() method keeps all those transformations in one place.

Let's see an example of a UserFactory that hashes a password before saving.

internal class UserFactory(private val hasher: Hasher) : EntityFactory<User, Users>() {
    override val table = Users

    override fun entity(): User {
        return User {
            firstName = faker.name().firstName()
            lastName = faker.name().lastName()
            email = faker.internet().safeEmailAddress()
            password = "secret"
        }
    }

    override fun transform(name: String, value: Any?): Any? {
        return if (name == "password") {
            hasher.hash(value.toString())
        } else {
            value
        }
    }
}

The "secret" password now will be hashed before persisting. Moreover, you can override the password while applying this factory, and the transformation will still be applied.

val hasher = app.make<Hasher>()

// The overriden password "mysupersecretpassword" will be transformed as well
val user = from(UserFactory(hasher), mapOf("password" to "mysupersecretpassword"))