The BeanUI Web/Rest Provider

© Thomas Schneider 2025-2026

generic bean/entity, server side rendered, single page web application

FEATURES

• full web application for any database connection with dialogs and selection assist
• single page application through server side rendering (spring-mvc / jte / htmx / beanui-core)
• connect to any database
• generate entity beans (reverse engineering) through any database
• online configuration of each entitiy bean ui
• different color themes
• responsive design
• nested relation dialogs, endless page scrolling, fuzzy finding filter, column sorting
• everything can be handled through shortcuts (shown in tooltips)
• extendable through plugins
• online database tools through openapi

Overview

TODO: wrap into plantuml markdown mindmap

@startuml BUIApplication (datbase-connection, registering beanui plugins) BeanUIController (main web application (spring mvc) rest endpoints) BeanService (mapping entities from repository into beanui objects) GenericEntityRepository (generic entity service) index -> main, nav main -> head, message, fatal, notification, modal_container container -> main, nav, content contentdialog -> content content -> contentrows contentrows -> rows beanui -> head, nav, fields fields -> uploadbutton @enduml

Installation / Start

find it on

• maven-central: https://repo.maven.apache.org/maven2/net/sf/tsl2nano/tsl3.beanui/0.0.2/tsl3.beanui-0.0.2.jar
• sourceforge : https://sourceforge.net/projects/tsl2nano/files/latest/download

and start in console:

  java -Dtsl3.beanui.preload.beanuis=false -jar tsl3-beanui-x.y.z.jar

after a while, open the page http://localhost:8080

Documentation

on default, the application starts a server, providing the handling of known beans and there relations. a default hsqldb datbase is started. see application.yaml to see the configuration of this database.

Menu and Theming

There are some dark/light and contrast themes. Switch between them on clicking the left symbol of the title 'BeanUI'.

The menu on the top left can open sidebar, showing all available beans/entities. on the top there is a simple search input field to filter the viewable items.

The top line shows some logging entries provided by the application.

add database model

you can generate a databae model and the jpa entities in one step. see next chapter

generate your first beans

Hit the menu button 'OpenAPI' on the top left and activate the panel generateEntitiesFromDatasource or go directly to: http://localhost:8080/swagger-ui/index.html#/metadata/generateEntitiesFromDatasource

Restart application to work on the new beans

after generating the beans - from default internal or any other external database, you have to restart the application. if you want the application to connect to the external database, you have to set some environment variables to connect to that database.

the generator writes a new .env file that provides these connection variables. so, you can start the following command:

  source .env

after that, start the application. the application will connect to the external database.

Through the top left dashed menu icon, you can open a sidebar to filter and activate a page for each bean/entity. On entering such a page, you always have an input filter bean items on the top left and a '+' button to create a new bean item.

a table of bean items (loaded through the given database (for the connection: have a look at the top right corner)) is loaded and is able to be scrolled until the end of all existing items. the header is sortable - and through a double click on a table row , you are able to open a edit dialog for the selected item.

Configuring the UI of your beans

The project is using the tsl3.beanui.core library. This provides peristable ui configurations on any bean. for further informations, see: ...TODO...

inside the folder presenter, you will see a json file for each bean. the json file lets you define constraints, presenter of the bean itself and all its attributes.

• the configuration can be changed online through: http://localhost:8080/swagger-ui/index.html#/metadata/getBeanUIConfiguration
• and save through: http://localhost:8080/swagger-ui/index.html#/metadata/saveBeanUIConfiguration
• or reset all configurations: http://localhost:8080/swagger-ui/index.html#/metadata/resetBeanUIs

not working feature for fast configuration

UNDER CONSTRUCTION: a click on the bean title provides a configuration dialog (json!) for the current bean type.

The Admin page (view only)

The admin page provides a simple viewing map of current system properties

Online application tools through OpenAPI

TODO

• [v] create cached bean descriptors with presenters
• [v] bean descriptors must be dynamic by adding attribute descriptors
• [x] provide JPA configuration through a persistence bean
• [x] run hibernate tools to generate beans from ddl
• [x] use spring CrudRepository as GenericService
• [x] check spring rest data handling crud on beans
• [v] objectmapper: +enum, +set
• [x] generate beans through ddl (hibernate-tools)
• [x] assign selectable values (@manytoone / foreignkeys)
• [x] provide selection button on container attributes (@onetomany)
• [x] validate input
• [x] provide action buttons
• [v] what about constraint format? we need a pattern?
• [x] on user input error, show error dialog
• [x] add service to search by example
• [v] read bean attribute annotation infos for constaints and presenter
• [v] beanui with map
• [v] add internationalization with translation
• [v] add websockets or flux for server messages
• [v] fill default values...
• [x] add on table: +sort, +filter, +paging, +search
• [x] attachments (files, icons etc.)
• [x] add framework entry points: PageNavigationMap(main, nav, container, ...), extract more jte templates
• [x] beanui de-serializing of formatted json fails
• [x] add bean type filter in context
• [v] add beanui pluggable to provide own valueExpressions
• [v] rename "fieldset" to "group" and use it on beans to group beanui-buttons in html-expandables
• [v] htmx seems to use child hx-target informations (like of a button) of sub html-fragments to put elements there - instead of using this - [v] provide a search field to filter the menu/action items
• [v] sorting DESC not working anymore
• [v] on generating beans, generate a messages resolving camelcase
• [x] add beanui.presenter.principle to let the server filter bean-buttons and attributes/fields by user roles and permissions
• [x] provide a configuration dialog on click on entity name
• [ ] sort of bean attributes: id as first attribute, followed by mandatories
• [ ] generate beans through openapi (swagger-codegen-maven-plugin)
• [ ] add security and user login with roles
• LAYOUT:
• [v] use htmx-min-2.0.8.js
• [v] table search not working: hibernate problem with cast(column as string)
• [x] replace explicit url pathes with '#'
• [v] provide main menu with all types
• [v] extract main layout
• [v] refactore "index" as simple start page, putting current index to container
• [v] add menu item for "admin" to edit a map of properties (-> core)
• [v] css themeing not working yet <- click on BeanEx icon
• [x] add properties for language, style-sheet, and main style-classes
• [v] add icons on type buttons (sidepane)
• [x] responsiveness: nav menu and table header must not be hidden on small displays
• [x] add layout fieldsets
• [v] sort buttons creating page without header
• [v] close button not working
• [v] sort direction not refreshed (<- simpliest way with only one sorting column!)
• [v] provide container list to add multiple dialogs to be nested
• [x] don't lose the current page on error messages
• [v] optimize high-contrast css on dialogs
• [v] for dialog nesting: specialize all html tag IDs (not only BEAN_TABLE, but BEAN_TABLE-${beanui.getName()})
• [v] single page mech. not working on "save" (do: "container" -> "row") <- form button should be type=button
• [v] dialog nesting not endless...
• [v] hibernate StreamCorruptedException on very long entities with lots of relations <- catch exception on getValue() and <Iterable>.toString()
• [v] type action filter should have focus
• [v] sidepanel close button not visible anymore
• [x] fix htmx-indicator as loading spinner
• [x] responsive design in dialogs
• [v] close dialog after request was valid
• [ ] moveable dialogs - initiate dialog on mouse (hover) position
• [ ] provide some icons
• [ ] add flag for using app as framework or test-tool (dev or prod) e.g. on message with exception
• INTERFACES:
  • [ ] integrate any workflow (simpliest nano or camunda)
  • [ ] frames/objects on urls to other sites
• TESTS:
• [x] http integration test checking against the current state
• [v] check openapi methods (e.g.: get configuration, set configuration - check reloading beanuis )
• [x] test plugin for generated messages.properties
• [ ] test/check beanui additional fields and action/buttons
• [ ] test BeanConfigurator
• OUTCOME:
  • [x] handle features on distribution jar file
  • [x] migrate pom and use tsl2nano to upload to maven-central
  • [x] pom version to 0.2, working then on branches
• QUESTIONS:
  • [v] manytoone input options: datalist or select?
  • [v] use fieldset? (at the moment we use a table)
• BUGS:
  • [ ] beandialog on save does always append changed item to table (cannot use 'closest tr:Bean_TABLE_BODY-${beanui.getName()}')
  • [ ] after formatting json file, it can't be loaded anymore. seems that unpretty() does not work every time...
  • [ ] send the websocket message to the current remote request - and not as broadcast
  • [ ] file upload button not working on firefox. does not send 'file' request attribute (selecting a file is not stored as value)

Problems/Solutions

• JTE seems to find project classes only (on jte pre-compilation)
• Caused by: java.io.FileNotFoundException: class path resource [org/springframework/boot/autoconfigure/web/servlet/WebMvcRegistrations.class] cannot be opened because it does not exist
• class is in: spring-boot-autoconfigure
• using spring-boot parent 3.2.3 does start only without any spring libraries jte and htmx. the spring depenendency plugin must be removed either.
• html items are displayed in wrong structures
• using hx-swap-oob in sub templates (fractionated) may cause this behavour. try not to use swap-oob in sub-templates. see: https://htmx.org/attributes/hx-swap-oob/#nested-oob-swaps
• hibernate StreamCorruptedException 'invalid stream header: 7B227661' on very long entities with lots of @OneToMany relations
• java serialization is limited in length. to enhance e.g.: -Djdk.serialFilter=maxarray=100000;maxdepth=20;maxrefs=500
• or out-comment the @OneToMay annotations and add @Transient (or remove these properties completely)
• or don't do 'getValue()' on that attribute (that may load the full list/set content - even if a lazyloading was defined)
• java.lang.IllegalArgumentException: de.tsl3.beanui.core.BeanUI$BeforeInit referenced from a method is not visible from class loader: 'app'
• start java -jar with option: -Dtsl3.beanui.preload.beanuis=false
• workaround for 'Circular View Path' errors in a Spring MVC:
• have a look into the jar file: perhaps generated JTE files aren't there. then, add jte-maven-plugin to generate and provide the jte classes in project target dir.