RFC: File Upload Support for Entity Fields via @Asset Annotation

[cromoteca]

Summary

Introduce an @Asset annotation for JPA entity fields in Hilla that transparently supports file upload and storage integration. The goal is to enhance CrudRepositoryService and entity-based endpoints to support File | string | undefined input on the client side, while decoupling file persistence from business logic. (Let's assume strings, although that can also be a number, a UUID or something else.)

Motivation

File handling in Hilla currently requires manual endpoint design, DTO mapping, and storage logic. This breaks the simplicity of CRUD-style editing via CrudRepositoryService.

By leveraging:

• Multipart support already present in Hilla's transport layer
• Jackson's ContextualDeserializer to inject field-specific deserialization logic
• Code generation to modify TypeScript types appropriately

the @Asset pattern can allow seamless full-stack handling of file fields, preserving the developer experience and performance benefits of the Hilla model.

Proposal

Java Usage

@Entity
public class Order {
  @Id @GeneratedValue
  private Long id;

  @Asset(handler = InvoiceFileHandler.class)
  @Column(nullable = true)
  private String invoiceFile;
}

TypeScript Generation

export interface Order {
  id: number;
  invoiceFile?: string | File;
  // or
  invoiceFile?: Asset<string>;
}

Runtime Behavior

• When a MultipartFile is submitted as the value of invoiceFile, it is passed to a custom AssetHandler implementation.
• The AssetHandler is user-defined and injected via Spring:

@FunctionalInterface
public interface AssetHandler<T> {
  T handle(MultipartFile file);
}

• The return value of handle(...) is used to populate the field (e.g., storing a path, ID, or URI).
• If the field value is null, the asset is deleted (field nullability should dictate if the file can be deleted).

Implementation Details

Jackson Integration

• Implement MultipartFileDeserializer as a ContextualDeserializer

• Use DeserializationContext.createContextual(...) to access:

  • Target property name
  • Type and annotations

• Look up the appropriate AssetHandler using Spring by Class (from annotation)

Annotation Definition

@Retention(RUNTIME)
@Target(FIELD)
public @interface Asset {
  Class<? extends AssetHandler<?>> handler();
}

File Upload Semantics

• string in the field: keep existing file (identified by ID)
• File in the field: upload new file and replace
• undefined: delete (if allowed)

Advantages

• Enables file upload via standard CRUD editing flows
• Eliminates need for extra endpoints or DTO mapping
• Developer controls persistence logic via AssetHandler
• Clean frontend experience: no new types or upload API

---

Notes

Example of enhanced deserializer (improving what's already in place):

public class MultipartFileDeserializer
        extends JsonDeserializer<MultipartFile>
        implements ContextualDeserializer {

    private @Nullable BeanProperty property;

    @Override
    public JsonDeserializer<?> createContextual(DeserializationContext ctxt, BeanProperty property) {
        MultipartFileDeserializer clone = new MultipartFileDeserializer();
        clone.property = property;
        return clone;
    }

    @Override
    public MultipartFile deserialize(JsonParser p, DeserializationContext ctxt) throws IOException {
        // Access annotation
        if (property != null && property.getAnnotation(Asset.class) != null) {
            // save the file and use the handler result as deserialized value
        }

        JsonNode node = p.getCodec().readTree(p);
        if (node instanceof POJONode pojoNode && pojoNode.getPojo() instanceof MultipartFile mf) {
            return mf;
        }

        throw new IOException("Expected MultipartFile in POJONode");
    }
}

As a reminder, Hilla is already capable to receive multiple files in a request and put them back in place at the good location in the parameters. So, we can perfectly receive 10 orders, for 3 of which there's a new invoice attached. The functionality has a guard that disallows using MultipartFile as entity property, but we can allow if @Asset is present.

[cromoteca]

A similar idea (with reverse logic) can be used when the file is actually stored in the database: a handler is needed when serializing to replace the value with a string (or whatever the replacement type is), and to handle the result back by saving the new value if a file is coming.

[cromoteca]

And those handlers could optionally do more, by offering a way to generate download links and handling GET requests for those links.