Tentackle Core — The Runtime Foundation¶

Overview and Motivation¶

The tentackle-core module is the runtime foundation of the framework. Sitting directly on top of tentackle-common — its only Tentackle dependency — it provides the cross-cutting runtime services that every higher layer (session, database, persistence, PDO, domain, FX) builds upon: remoting, reflection-based proxying and interception, binding, validation, logging, scripting, tasks, preferences, I/O and a large kit of general-purpose utilities.

Where tentackle-common is the dependency-free layer shared between build time and runtime, tentackle-core is the first genuinely runtime layer. It is where the framework's defining mechanisms live:

TRIP — the custom serialization/RPC protocol that replaces RMI and Java Object Serialization and makes PDOs travel transparently between JVMs.
Interceptable proxies — the dynamic-proxy and interceptor machinery that lets a PDO combine its domain and persistence delegates and that implements @Transaction, @Log and friends.
Binding and Validation — the model↔view binding engine and the annotation-driven, scope-aware validation framework.

Several of these subsystems are large enough to have their own dedicated documents; this page is the map of the whole module and links to them where they exist.

Topic deep-dives in this folder: trip.md · interceptors.md · binding.md · validation.md

Design principles¶

Pluggable everything. Almost every subsystem is exposed as an interface located through the service API (Logger, ScriptingLanguage, ClassMapperFactory, PersistedPreferencesFactory, the TRIP providers, …), so an application can replace any of them by registering its own @Service.
Annotation-driven behavior. Cross-cutting concerns (interception, logging, validation, TRIP type handling) are attached declaratively via annotations and woven in through proxies and build-time annotation processors, not handwritten boilerplate.
Modular and classpath parity. Like the rest of the framework, everything works identically under JPMS and on the classpath; the module even contains workarounds (the uses clauses for Logger/ScriptingLanguage) for non-modularized providers loaded from jimage files.
No higher-layer knowledge. Core knows nothing about sessions, SQL or domain objects — those depend on it.

Key Subsystems¶

TRIP — remoting and serialization¶

Packages org.tentackle.trip, trip.builder, trip.creators, trip.impl, trip.provider, trip.remote, trip.transport, trip.types.

TRIP (Tentackle Remote Invocation Protocol) is the framework's own serialization and RPC stack — by far the largest subsystem in the module (~190 files). It replaces RMI/JOS with a protocol designed for the PDO model: objects and proxies are serialized via a pluggable type system, and methods can be invoked across JVMs (client↔ server and server↔server). The subdivision is:

trip — the core API (TripType, TripTypeBuilder, the protocol entry points, TripReferencable and the serialization annotations).
trip.types / trip.builder / trip.creators — the predefined TripTypes and the builders/creators that produce them for concrete Java types.
trip.impl / trip.provider — default implementations and component providers (including the default ObjectSerializer that TBinary uses).
trip.remote — the remote-invocation protocol layer (transport-independent RPC).
trip.transport — the concrete transports (e.g., SSL sockets) that carry the protocol.

See trip.md for the full treatment.

Reflection, proxies and interception¶

Package org.tentackle.reflect (plus the build-time apt processors).

This package provides two intertwined capabilities:

Class mapping — ClassMapper / ClassMapperFactory (and the Default* impls, ClassToServicesMapper, ClassMappedListener) map names/interfaces to their implementation classes — the runtime side of the service API used to resolve PDO/domain/persistence implementations.
Interceptable proxies — Interceptable, InterceptableFactory, InterceptableInvocationHandler, Interceptor and the @Interception meta-annotation form the dynamic-proxy engine that lets a PDO weave domain and persistence delegates together and apply cross-cutting interceptors around method calls. Mixin, PropertyMap, ReflectionHelper, ReflectiveVisitor and the canonical-constructor annotations (@CanonicalConstructor, @CanonicalField, @CanonicalGetter, …) round it out.

See interceptors.md for how interception is declared and applied.

Binding¶

Package org.tentackle.bind.

The binding engine connects model properties to views (typically JavaFX), keeping them in sync without manual listener wiring. It is the foundation the FX modules build their auto-binding on. See binding.md.

Validation¶

Packages org.tentackle.validate, validate.scope, validate.validator, validate.severity.

An annotation-driven, scope-aware validation framework: validators (validate.validator ships ~65 predefined ones) are attached to model fields/methods and run within a ValidationScope (e.g., mandatory vs. save vs. delete), producing results at graded severities. See validation.md.

Logging¶

Package org.tentackle.log.

A pluggable logging facade: Logger / LoggerFactory abstract the backend, with DefaultLogger on top of java.util.logging (the module uses Logger so alternative providers can be supplied). Beyond plain logging it offers:

MappedDiagnosticContext (MDC) for contextual logging.
The @Log annotation + LogInterceptor to log method calls declaratively (an example of the interception engine in use).
MethodStatistics / StatisticsResult for collecting per-method execution counts and durations.

Tasks and dispatchers¶

Package org.tentackle.task.

Task and TaskDispatcher (with AbstractTask / DefaultTaskDispatcher) provide serialized task execution on a single worker thread. This is the base that tentackle-session's SessionTaskDispatcher, keep-alive daemon and modification tracker extend.

Scripting¶

Package org.tentackle.script.

A scripting abstraction layer: ScriptingLanguage / Script / ScriptFactory let the framework evaluate scripts (e.g., in validators or the model) independently of the concrete engine; the module uses Logger/ScriptingLanguage so providers can be plugged in.

I/O and networking¶

Package org.tentackle.io.

Building blocks used by the TRIP transports and elsewhere: compressing/decrypting streams (CompressedInputStream, EncryptingOutputStream, …), packet-framed streams (PacketSizedInputStream), notifying byte-array streams, the SocketChannelDispatcher for accepting client connections, and the reconnection machinery (Reconnector, ReconnectionPolicy) that lets dropped connections recover.

Preferences¶

Package org.tentackle.prefs.

PersistedPreferences / PersistedPreferencesFactory abstract the standard java.util.prefs API so it can be backed by different stores (e.g., the database-backed implementation in tentackle-database), with CompositePreferences combining user and system nodes.

Daemon supervision¶

Package org.tentackle.daemon.

DaemonSupervisor controls the life cycle of long-running background threads (Supervisable, Killable, Scavenger, Terminatable) — used for cleanup threads, keep-alive daemons and the like.

Miscellaneous utilities¶

Packages org.tentackle.misc and org.tentackle.misc.time.

The framework's general-purpose toolkit (~70 files). Highlights:

Pooling — AbstractPool / Poolable / AbstractPoolSlot, the base for the session pools.
Collections — copy-on-write wrappers (CopyOnWriteList, …Set, …Collection), TrackedList, holders and tuples (IdSerialTuple, IdSerialNameTuple).
Functional helpers — Acceptor/Provider (checked-exception-friendly Consumer/Supplier), Holder, BlockingHolder, Convertible.
Formatting & parsing — FormatHelper, CsvConverter, CommandLine, DateTimeUtilities and the smart date/time parser in misc.time (SmartDateTimeParser with its shortcuts and missing-field handlers for forgiving user input).
Concurrency — ConcurrencyHelper.
Diagnostics — DiagnosticUtilities (extended by the database layer to enrich stack dumps), Identifiable, Canonicalizer.

Annotation processors (build time)¶

Package org.tentackle.apt (and apt.visitor).

The build-time annotation processors that back core's annotations — chiefly the interception processors (InterceptionAnnotationProcessor, AbstractInterceptorAnnotationProcessor, …) and the service-annotation base (AbstractServiceAnnotationProcessor). These run during compilation/analysis (see the service & configuration API) and emit the META-INF configuration consumed at runtime.

Package Layout¶

Package(s)	Subsystem	Reference
`org.tentackle.trip` (+ `builder`, `creators`, `impl`, `provider`, `remote`, `transport`, `types`)	TRIP remoting/serialization	trip.md
`org.tentackle.reflect`	Class mapping, interceptable proxies, reflection helpers	interceptors.md
`org.tentackle.bind`	Model↔view binding	binding.md
`org.tentackle.validate` (+ `scope`, `validator`, `severity`)	Validation framework	validation.md
`org.tentackle.log`	Pluggable logging, MDC, `@Log`, method statistics	—
`org.tentackle.task`	Serialized task dispatchers	—
`org.tentackle.script`	Scripting abstraction	—
`org.tentackle.io`	Streams, sockets, reconnection (TRIP transport building blocks)	—
`org.tentackle.prefs`	Pluggable persisted preferences	—
`org.tentackle.daemon`	Background-thread supervision	—
`org.tentackle.misc` (+ `misc.time`)	General-purpose utilities, pooling, smart date/time parsing	—
`org.tentackle.apt` (+ `apt.visitor`)	Build-time annotation processors	—
`org.tentackle.service`	The `Hook` (`ModuleHook`)	—

How It Fits Together¶

tentackle-core is the layer where the framework's runtime mechanisms first appear, and almost every other module consumes one or more of its subsystems:

   FX / RDC ──── binding, validation, scripting, smart date/time parsing
   pdo / domain ─ interceptable proxies (Interceptable), TRIP, validation
   persistence ── TRIP remote delegates, tasks, diagnostics
   database ───── TRIP transport, tasks, persisted preferences, reconnection
   session ────── tasks (SessionTaskDispatcher), TRIP (remote sessions)
        │
        └──────────► tentackle-core (TRIP, reflect, bind, validate, log,
                      task, script, io, prefs, daemon, misc)
                          │
                          └──► tentackle-common (services, data types)

For example, a PDO is an Interceptable proxy (reflect) whose @Transaction/@Log methods are wrapped by interceptors; when it travels to a server, it is serialized with TRIP; its fields are validated through the validation framework and bound to FX controls through the binding engine; the server's background work runs on task dispatchers supervised by the daemon package over io transports. All of this is configured through the service API from tentackle-common.

Module Dependencies¶

It requires transitive only tentackle-common from Tentackle, plus java.prefs, java.management and java.logging from the JDK.
It uses org.tentackle.log.Logger and org.tentackle.script.ScriptingLanguage so that non-modular providers remain visible even in jlink'd images.
It opens org.tentackle.common (via tentackle-common) and its own serialized packages to TRIP, and provides a ModuleHook (org.tentackle.service.Hook).
Every Tentackle module above this one — session, sql, database, pdo, domain, persistence, the FX stack — depends on it transitively.

TRIP — the remoting/serialization protocol.
Interceptors — annotation-driven method interception and the interceptable proxy engine.
Binding — connecting models to views.
Validation — annotation-driven, scope-aware validation.
Services / ServiceFinder — the SPI that makes every core subsystem pluggable.
Session — builds tasks, dispatchers and remoting on top of core.