SDK 0.7.8-RELEASE Repository Migration

English

Note: If your project does not use ApiHug domain entity management, this migration will likely have limited impact on your project.

Latest:

0.7.8-RELEASE introduced:

• Repository @Derived maintenance moved into a dedicated trait source set.
• lite became the default model on the stub side.

Repository Migration

Goals:

1. Keep generated repositories clean and predictable.
2. Move derived repository logic into a location that is easier to maintain.

Use an existing repository such as com.novel.book.wire.domain.book.repository.BookAuthorRepository in module book-app as the example below.

Current location: book-app\src\main\stub\com\novel\book\wire\domain\book\repository\BookAuthorRepository

@Repository
@SuppressWarnings("Duplicates")
public interface BookAuthorRepository
    extends HopeJdbc<BookAuthor>,
        BookJdbcSupport,
        BookAuthorDSL,
        ListCrudRepository<BookAuthor, Long> {

  @Derived
  @Query
  Optional<BookAuthor> findByName(final String name);

  // Other methods
}

Important: Back up your @Derived methods before running the stub command.

After this change, the stub directory is treated as generated output and can be overwritten by the next stub run.

Step 1

Update the SDK version in gradle\libs.versions.toml:

[versions]
# libraries
apihug = "0.7.8-RELEASE"

Then run the module stub command. The exact command is usually documented in your project's README.md:

./gradlew.bat book-app:clean stub build -x test -x stubTest

After the command succeeds, you will see a new source set: book-app\src\main\trait.

Tip: You may need to run Reload Gradle Project from the Gradle tool window. Otherwise, book-app\src\main\trait may not be recognized as a source set.

Step 2

1. Move the backed-up @Derived methods into _BookAuthorRepository under the trait directory.
2. Keep the old repository temporarily compilable during the first migration.
3. Run the stub command again.

After that, all @Derived repository methods are maintained under book-app\src\main\trait.

1. The stub task merges those methods back into the runtime BookAuthorRepository.
2. BookAuthorRepository stays cleaner because generated template code and custom derived logic are separated.
3. SQL-oriented trait logic becomes easier to maintain over time.

Manual Path

This migration path involves more manual work, but it is still practical for smaller projects.

1. Create directory book-app\src\main\trait
2. Create package t.com.novel.book.wire.domain.book.repository, using t. as a prefix over the original package
3. Add trait interface _BookAuthorRepository, using _ as a prefix over the original BookAuthorRepository
4. Make it extends BookAuthorRepository
5. Copy the @Derived methods from BookAuthorRepository into _BookAuthorRepository
6. Run the stub command

This approach is still workable when the number of repositories is manageable, for example fewer than 30.

Project directory structure

+---java
|   \---com
|       \---novel
|           \---book
+---stub
|   \---com
|       \---novel
|           \---book
|               \---wire
|                   \---domain
|                       +---account
|                       |   +---dsl
|                       |   \---repository
|                       +---book
|                       |   +---dsl
|                       |   \---repository
|                       \---job
|                           +---dsl
|                           \---repository
\---trait
    \---t
        \---com
            \---novel
                \---book
                    \---wire
                        \---domain
                            +---account
                            |   \---repository
                            +---book
                            |   \---repository
                            \---job
                                \---repository

Later Improvement

Since SDK 0.8.5-RELEASE, later releases introduced an easier maintenance pattern.

After you define an entity in your proto and run the stub command, you will also get an empty trait repository:

/**
 * NEVER try to use this class directly, keep it as an interface(default, no public), all body of
 * this interface will be merger to {@link JobEntityRepository} after {@code stub };
 *
 * <p>NEVER try to Overwrite parent {@link JobEntityRepository } or {@link
 * org.springframework.data.repository.ListCrudRepository} 's default method!!
 *
 * @see JobEntityRepository
 * @see com.novel.book.wire.domain.job.JobEntity
 */
interface _JobEntityRepository extends JobEntityRepository {

  /** Please put your customized SQL here, any SQL other place will be dropped after merger! */
  interface _DerivedSQL {}
}

Then you can add a customized DAO API:

@Overwrite
default void myDaoApi() {

}

Remember to add @Overwrite to this method. IDEA will then suggest Pull method 'myDaoApi' to 'JobEntityRepository'.

Follow the IDEA action so the method moves to the parent interface and you can avoid an extra stub cycle.

After the next stub run, the same logic remains in place.

Best Tips

You can think of _BookAuthorRepository as a companion interface for BookAuthorRepository.

The ApiHug tool chain handles the merge workflow for you.

See also Companion objects in Scala.

If you run into upgrade issues, contact the ApiHug team: