Tool Methods

Jimmer provides a series of static tool methods for operating on dynamic objects or their Drafts.

info

For brevity, this article only lists the strongly typed usages.
There are also weakly typed versions of these refactoring methods.

Operating on Immutable Objects

isLoaded

• Purpose: Determine if a property of a dynamic object is loaded

Java

if (ImmutableObjects.isLoaded(book, BookProps.AUTHORS)) {
    ...
}

Kotlin

if (isLoaded(book, Book::authors)) {
    ...
}

get

• Purpose: Dynamically get a property of an object

• Exception: The property of the object is in an unloaded state

Java

List<Author> authors =   
    ImmutableObjects.get(book, BookProps.AUTHORS);

Kotlin

val authors = get(book, Book::authors) 

isIdOnly

• Purpose: Check if a dynamic object is only set with an id property

• Precondition: The object type is annotated with @Entity and is an ORM entity with an id

Java

if (ImmutableObjects.isIdOnly(book)) {
    ...
}

Kotlin

if (isIdOnly(book)) {
    ...
}

makeIdOnly

• Purpose: Construct an object of the given type and set its id property

• Precondition: The object type is annotated with @Entity and is an ORM entity with an id

Java

Book book = ImmutableObjects.makeIdOnly(Book.class, 1L);

Kotlin

val book = makeIdOnly(Book::class, 1L)

tip

• For Kotlin, the id parameter must be non-null, and the return value is also non-null.

  To accept a possibly null id and directly return null when id is null, call makeNullableIdOnly

• Java's makeIdOnly is actually equivalent to Kotlin's makeNullableIdOnly.

isLonely

• Purpose: Check if an object is only set with an id property. I.e. no associated properties are set to non-null (including unset and set to null).

  info

  If the object is an ORM entity, it is an exception if a one-to-one or many-to-one property based directly on a foreign key is set to an associated object with only an id.

Java

if (ImmutableObjects.isLonely(book)) {
    ...
} 

Kotlin

if (isLonely(book)) {
    ...
}

toLonely

• Purpose: Create a new object based on an existing object. The new object copies all non-associated properties from the old object, but all associated properties remain unset.

  info

  For ORM entities, special handling is performed for one-to-one and many-to-one properties based directly on foreign keys. These are set to associated objects with only ids or null.

Java

Book lonelyBook = ImmutableObjects.toLonely(book);

Kotlin

val lonelyBook = toLonely(book) 

toIdOnly

• Purpose: Create a new object based on an existing object. The new object only copies the id property from the old object.

• Precondition: The object type is annotated with @Entity and is an ORM entity with an id

Java

Book lonelyBook = ImmutableObjects.toIdOnly(book); 

Kotlin

val lonelyBook = toIdOnly(book)

Or

Java

List<Book> lonelyBooks = ImmutableObjects.toIdOnly(books);

Kotlin

val lonelyBooks = toIdOnly(books)

fromString

• Purpose: Shortcut for JSON deserialization

Java

Book book = ImmutableObjects.fromObject(
    Book.class, 
    "{\"id\":1,\"name\":\"Learning GraphQL\",\"authorIds\":[2,1]}"   
);

Kotlin

val book = fromString(
    Book::class,
    """{"id":1,"name":"Learning GraphQL","authorIds":[2,1]}"""  
)

Operating on Mutable Drafts

set

• Purpose: Dynamically set Draft properties

Java

Book newBook = Immutables.createBook(book, draft -> {
    DraftObjects.set(draft, BookProps.AUTHOR_IDS, Arrays.asList(1L, 3L)); 
});

Kotlin

val newBook = Book(book) {
    set(draft, Book::authorIds, listOf(1L, 3L))
}

unload

• Purpose: Unload a Draft property, i.e. mark a property as unloaded

Java

Book newBook = Immutables.createBook(book, draft -> {
    DraftObjects.unload(draft, BookProps.AUTHOR_IDS);  
});

Kotlin

val newBook = Book(book) {
    unload(draft, Book::authorIds)
}

show

• Purpose: Show a property

Java

Book newBook = Immutables.createBook(book, draft -> {
    DraftObjects.show(draft, BookProps.AUTHOR_IDS);
});

Kotlin

val newBook = Book(book) {
    show(draft, Book::authorIds) 
}

hide

• Purpose: Hide a property

Java

Book newBook = Immutables.createBook(book, draft -> {
    DraftObjects.hide(draft, BookProps.AUTHOR_IDS); 
});

Kotlin

val newBook = Book(book) {
    hide(draft, Book::authorIds)
}