Converting the project to a multi-module project

[philliplbryant]

As part of the work I am doing for issue #13, I refactored the project into a multi-module project and separated build-logic into an included build. This allows the persistence framework, which would be incorporated in a follow on task, to remain separate from the rest of BentoFX and gives users the ability to continue using the docking framework without persistence.

I am proposing the following structure, where modules and directories in bold would be introduced as part of this task. Other modules are planned for future introduction and are shown for additional context.

For my Team's applications - which will be using BentoFx - we have done a lot of work creating reusable build logic that is highly refined, performant, and tested. With your permission, we will integrate some of our build logic into this project and make the changes necessary to use it. The build logic:

• Will DRY up (don't repeat yourself) Gradle configurations, enabling them to be and shared among modules.
• Pre-compiles, making builds faster.
• Uses Gradle's configuration cache, making builds faster.
• Uses Gradle's build cache
  • Tasks are only executed when they are not up-to-date.
  • Build outputs are also cached; when a task is up to date, but its outputs are missing (e.g. after executing clean), the outputs are retrieved from the build cache rather than being reconstructed.
• Uses a version catalog to help ensure dependencies are consistently versioned
• Uses type-safe accessors for all dependency declarations

Our build logic is currently implemented in Kotlin, but we can convert it to Groovy before final submission if that is preferred.

@Col-E, if it make sense to do so, and it helps move this request forward, I am willing to work with you to integrate this build logic into your Recaf project.

I don't want to impose any unwelcome changes but I am offering to make changes that I believe will be beneficial to the project.

As I mentioned in another issue, I ran into an administrative issue with my employer that is delaying me from creating a pull request with these changes. I'd be happy to share the work if you're interested in and are willing to wait a few more days while I work to resolve the admin issue with my employer?

Here's the project layout I am currently using:

BentoFx
 assets
  Existing files with added markdown documents and diagrams for persistence framework.
 build-logic
  Shared Gradle configurations
 core
  The existing docking framework, moved from the single-module project, with minimal changes to reuse build logic.
 demos
  basic-demo
   Moved from the current src/test/java directory of the single-module project
  persistence-demo
   The basic-demo modified to use the persistence framework
 gradle
  libs.versions.toml
   This is where dependencies and dependency versions are declared for consistency and re-use among    modules
 persistence
  api
   Common, core functionality for persisting bento layouts
  codec
   common
    Common, core functionality for encoding/decoding bento layouts
   json
    Functionality specific to encoding/decoding bento layouts in JSON format
  xml
   Functionality specific to encoding/decoding bento layouts in XML format
  storage
   db
    h2
     Functionality specific to writing/reading bento layouts from an H2 database
   file
    Functionality specific to writing/reading bento layouts from a file on the local file system
   test-fixtures
    Sharable classes that are used by tests - mocks behavior for things like codec and storage implementations
 platform
  Dependency constraints and alignment
 build.gradle
  Modified to apply additional plugins
   Dependency Analysis Gradle plugin
    Provides advice for managing dependencies and other applied plugins
    https://github.com/autonomousapps/dependency-analysis-gradle-plugin
   JVM Dependency Conflict Gradle plugin
    Managing JVM dependency conflicts in Gradle
    https://github.com/gradlex-org/jvm-dependency-conflict-resolution
   Versions Check Gradle plugin
    Checks dependency and Gradle updates in the spirit of the Maven Versions Plugin
    https://github.com/ben-manes/gradle-versions-plugin

[philliplbryant]

I believe these changes will also handle issues #19, #20, #22, and #23. I'd be happy to make those changes and include them if I haven't already.

[andrej-urvantsev]

Sorry to jump in, but do you guys want to introduce persistence layer into docking framework?

I suggest to avoid this. Follow UNIX philosophy: "do one thing, but do it well".

Docking framework should do one thing: window docking, persistence should not be part of it I believe.

[philliplbryant]

Hi @andrej-urvantsev,

Are you concerned with the proposed project structure or the idea of adding persistence modules to the framework altogether? For the record, I'm not proposing introducing the persistence modules in this task. I would restructure the existing project into multiple modules, and introducing the persistence modules separately. I apologize if I did not make that clear.

I can't speak for @Col-E, but persisting the docking layout between application executions is a must have feature for us. Imagine opening the application, making dynamic changes to the layout using drag and drop and other features provided by BentoFX, exiting the application, and discovering all of your changes were lost. The end result would be requiring users to recreate their layouts every time they stop and restart the application.

IntelliJ, and many other applications that use docking frameworks, save the layout. And JIDE, a Swing based docking framework that we are replacing with BentoFX, provided layout persistence.

I agree with your goal of doing one thing and doing it well, but in this case, I think that should apply to individual modules in BentoFX. A framework is a set of libraries. And I think adding modules to the framework that provide the ability to persist the docking layout between application executions fits well.

[andrej-urvantsev]

The latter - persistence layer is not a part of docking framework imho. One application needs it, another does not. One would like to save state on disk, another in DB, third one to call a REST API.

The moment you introduce persistence layer, you also get problems like data migration(imagine that you've changed format and new version should recognize old format and convert to the supported one).

Also, how do you persist dynamically created windows? What if saved state does not match runtime anymore?

All those above mentioned things are application specific and shouldn't be a part of docking framework. To not mention additional dependencies which can open another can of worms: what if your json/xml libraries will conflict with existing in the project?

The less opinionated framework is, the easier integration and adoption. And maintenance.

[philliplbryant]

@andrej-urvantsev,

I respect and appreciate your opinion. Hopefully my position will become more clear when I'm able to post the actual code.

As implemented, the "core" docking framework remains completely independent of the persistence modules, which are published as separate artifacts. You would only get persistence functionality by explicitly adding dependencies to storage and codec implementations (as defined by the persistence API).

I provide storage implementations for H2 database and a file and I provided codec implementations for XML and JSON. I also provide an example showing users how to extend the persistence layer so they can implement additional codecs (YAML, etc.) and storage destinations (REST API).

You make a valid point on versioning - one I have considered as well but not yet implemented. The initial release will not account for migrating different layout versions. Migration would be implemented in a follow on task or tasks. I have also planned and designed for other features like saving/restoring multiple docking layouts versus just the most recent one.

Concerning dynamically created Windows. You are correct the persistence framework can't know which Window or where in the Window layout the docking layout is to be applied. I persist the states of Bento instances, which contain the information necessary to recreate the docking layout, which is then applied by the user application. I demonstrate this in a demo application as well. I've tried to do so similarly to other docking frameworks, such as JIDE.

And dependency management has always been a problem with frameworks (try using Spring in a large project or consider "DLL hell" in the Microsoft world). The Gradle changes I propose introducing as part of this effort will help manage dependency constraints and alignment for the docking framework. It is up to framework users to do similarly in their applications. This is the case will all libraries. Gradle provides platforms to do so.

[andrej-urvantsev]

Yeah, that's what I mean exactly - why H2? Why not PostgreSQL or Java Preference API, or yaml/toml/xml/json/properties/Ini?

I believe that any framework/library should draw a line: what it does and what's more important - what it does not.

I'm getting really suspicious about any project which aims to be a Swiss Army knife.

I really would like at least one Docking framework in JavaFX to thrive, but I don't believe that turning Docking framework into Application framework is a good way to go.

Don't get me wrong - you do can have persistence and whatnot, but inside YOUR application, the way YOU want it.

The problem with "It's nice to have it here", that once you release it - there will be somebody who use that feature and it's hard to remove things afterwards.

Look at https://github.com/TestFX/TestFX project for example. There are so many nice to have things baked together, that it is really hard to move this project forward.

I tried to modernize it and create a PR, but ended up by rewriting a lot around it: https://gitlab.com/fx-labs/TestFX

Do things right, but also, do right things 😉

[philliplbryant]

So, what exactly are you proposing? Every BentoFX user who wants to persist the docking layout write their own persistence framework entirely from scratch?

I agree the framework should be lowly coupled, but it should also be highly cohesive. If the framework can only do one thing then there's zero cohesion. To your Linux referral: Linux provides a set of tools that can be used together. That's all the persistence modules would be doing: providing additional tools, that can be used together with the docking framework, to do something a docking framework would (and I argue should) normally do.

To be clear, I'm not proposing this project account for every variation of codec and storage. But I think it should include at least two, commonly used, independent examples of each to demonstrate how users can implement their own variations that can be easily integrated into their projects without the need to modify this framework. And, I believe, that's exactly what I've done.

[andrej-urvantsev]

Every BentoFX user who wants to persist the docking layout write their own persistence framework entirely from scratch?

Yes! Exactly!

If they need it, the way they want it, using storage they prefer and dependencies for serialization/deserialization of the state which they already use, with their unique way of working with inconsistencies, migration paths, conflicts and whatnot.

Every application is unique and have different demands. There is no way to satisfy everyone.

But I think discussion is going in circles, and it's up to the maintainers to make this decision. It's a strategic decision and important one: be a Swiss Army knife and build an "Application framework" or "Do one thing, but do it well".

[Col-E]

Persisting the docking layout between application executions is a must have feature for us.

While its not something I use in my own personal projects atm, I can see others coming from JIDE, DockingFrames, etc looking for an FX alternative and this being a desired feature. Overall, I do want to have Bento expose a mechanism for persisting layouts. Will break this down by conversation topics in this thread.

Unix / Anti-Bloat

I do agree with the notion of doing one thing and doing it well. I think that persisting docking layouts can be included in the "one thing" and does not encroach into becoming an application framework. We can offer plenty of features in ways that do not bloat the project from a consumer's standpoint.

1. No forced transitive dependencies
2. No forcing users into "opinionated" design patterns / a specific application model

No forced transitive dependences

We don't want to make assumptions, or force certain tech stacks / libraries on users aside from our own.

Thus, we should offer this persistence layer in a manner that does force a transitive dependency on the user. Consider Feign and how it handles JSON mapping of REST data objects. Rather than forcing the user into Jackson, Gson, etc they let you plug in your own library to an abstract converter system. If you are happy to include one of those libraries they offer implementations with each. So if you are on a project using Jackson, go with feign-jackson, and feign-gson if you already use Gson. But if you have a fancy in-house JSON parser? Sure plug it in.

No forcing of opinionated design patterns

I get the concern with Bento becoming an application framework with work like this. We can keep things modular so that users who want this don't have to completely re-invent the wheel (Maybe they'll want to decorate it a bit, but I digress). For the users that don't want this, if its in a separate module they can just pull in :core and not use :persistence.

I point back to the prior point with it being flexible.

• You wanna do it your way? We have a baseline persistence module that you plug into.
• You don't care how it work so long that it does? Here's a default implementation in a separate module you can use.

Other points

how do you persist dynamically created windows?

I haven't looked at any implementation of persistence thus far, but this is my first naive thoughts on the matter:

Map<DockContainerRootBranch, Window> rootToWindow = bento.getRootContainers().stream()
		.collect(Collectors.toMap(root -> root, root -> root.asRegion().getScene().getWindow()));
Map<Window, List<DockContainerRootBranch>> windowToRoots = rootToWindow.entrySet().stream()
		.collect(Collectors.groupingBy(Map.Entry::getValue, Collectors.mapping(Map.Entry::getKey, Collectors.toList())));
windowToRoots.forEach((window, roots) -> {
	// Arbitrary path per window.
	//
	// Persist impl could be in any format, JSON is an example but could be XML, or some binary format.
	// Important part is we don't force any specific format on the user.
	Path persistPath = Paths.get("persist/window-" + window.hashCode() + ".json");
	
    // Ideally you just have one root per window. Since when you drag a dockable out of its space it will
	// become a new window with the root as the scene's content it should be safe to assume most windows
	// only have one root.
	byte[] persistData;
	if (roots.size() == 1) {
		persistData = bento.persistFactoryThing().persistRoot(roots.get(0));
	} else {
		persistData = bento.persistFactoryThing().persistRoots(roots);
	}
	Files.write(persistPath, persistData);
});

Restoring would be something like:

• DockContainerRootBranch root = bento.persistFactoryThing().restoreRoot(path)
• List<DockContainerRootBranch> roots = bento.persistFactoryThing().restoreRoots(path)

What you do with those would be up to you. Say for instance I only care about the "primary" window. I could just write one root, and ignore all the others. When I relaunch my application, wherever I use Bento, I can just plop the restored instance back rather than make a new one with the default layout. In this setup, Bento only offers you a serialization model more or less. The layout contained within the docking containers are kept, but putting that somewhere in your user interface would be your job.

Seems like a reasonable middle ground. Thoughts?

versioning and data migration problems

Building on prior points made thus far, we can let the user handle issues like this if they wish in their own implementations. If we have our own reference implementations we could choose to handle this, but also choose to not do so if its too much of a pain point.

I've seen migration handling turn into monstrous messes and quite frankly if it were just me working on persistence for my own purposes I would say "oh well, we changed the format". Ideally the format wouldn't be so fragile, but again I haven't really looked into much of this myself since its been my understanding this would eventually be contributed anyways.

Yeah, that's what I mean exactly - why H2? Why not PostgreSQL or Java Preference API, or yaml/toml/xml/json/properties/Ini?

Why not Java ObjectOutputStream?

Jokes aside, I think it would be best if we only have a simple/lightweight reference implementation. Something like using H2/PostgreSQL or even REST (since I saw that earlier in the thread) would be left to a user implementation.

[Col-E]

Separate comment for comments on the actual content of the original issue, since my last one turned into a wall of text...

---

For persistence:

• :persistence:api 👍
• :persistence:codec 👍
• :persistence:codec-json 👍
• :persistence:codec-xml 👍 - Would pick this or json for a reference implementation, leaning towards json
• :persistence:codec-storage ❌ This is where I do agree that we venture into the "too much for one library" territory

It sounds like you have some rather advanced use cases for the persistence layer. From the prior comment I 100% agree we should expose an API/codec system to let users plug in their own tech stack for persistence. I'd like to also have a simple reference implementation to show users how they could implement the API, but IMO something like GSON would be a good fit for the "simple" description I'd be looking for.

For gradle:

libs.version.toml 👍

:platform 😕 - Not sure what this description really means or why it would be necessary.

I don't really see why we'd need any of these plugins for Bento.

• Dependency Analysis
  • I only really see Bento depending on JFX, and maybe one other library for the reference codec implementation. I don't see a plugin that checks for unused dependencies, transitive bloat, etc being useful.
• Dependency Conflicts
  • This plugin really only seems like it would make sense if you're making a large library. they mention conflicting slf4j logger implementations, but that is really an artifact of people not realizing their library depends on the binding/impl and not the api. The other one mentions Jakarta which is more enterprise world than I think Bento will ever end up touching out of the box.
• Versions Check:
  • So, another thing I really don't get is why as a JavaFX library you'd even care about the version you build against. Bento shouldn't be what ends up pulling JavaFX into your project as a consumer. So long as API contracts don't break we could probably get away with compiling against JavaFX 11. The main situation I see updating being a benefit for would be with running the demos.

[andrej-urvantsev]

I like the idea of providing API without concrete implementations, so users can plug-in their own.

And again, maybe first play a bit with a "reference" implementation to understand what is required from that API and if there is a need in the API at all - maybe some good example/documentation is enough.

Don't rush to add things 😉