1 package de.spiritscorp.datasync.controller;
2
3 /*-
4 * Data Sync
5 *
6 * Copyright © 2022 The Spirit
7 * @email thespirit@spiritscorp.network
8 *
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 3 of the License, or
12 * (at your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
17 * See the GNU General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with this program. If not, see <http://www.gnu.org/licenses/>.
21 */
22
23 import de.spiritscorp.datasync.gui.Gui;
24 import de.spiritscorp.datasync.theme.AppTheme;
25
26 /**
27 * Core architectural interface decoupling user interface interactions from business logic orchestration.
28 * Acts as the primary controller boundary for all GUI-driven events.
29 * * @author Tom Spirit
30 */
31 public interface ViewController {
32
33 /**
34 * Registers a native host operating system runtime shutdown hook within the virtual machine
35 * to intercept external termination signals.
36 * <br>
37 * This hook acts as a defensive fallback mechanism that catches OS-level interrupts such as
38 * SIGTERM, unexpected system logoffs, or manual console terminations (e.g., Ctrl+C). Upon
39 * interception, it ensures a controlled transition to essential cleanup routines, allowing the
40 * application to preserve data integrity, flush pending transaction logs, and prevent file
41 * system corruption before the JVM process is completely killed by the host environment.
42 *
43 */
44 void registerNativeShutdownHook();
45
46 /**
47 * Requests an orderly, programmatic termination of the entire application ecosystem.
48 * <br>
49 * Unlike defensive signal trapping, this method orchestrates the intentional, graceful shutdown
50 * lifecycle of active runtime components. It systematically cancels active synchronization tasks,
51 * halts scheduled background thread daemons, safely releases locked file descriptors, persists
52 * outstanding preference states to disk, and ultimately triggers a clean exit of the JavaFX
53 * platform runtime environment.
54 *
55 */
56 void handleApplicationShutdown();
57
58 /**
59 * Asynchronously dispatches the orchestration engine onto a background worker thread.
60 * Optionally defers the initial execution sequence to accommodate bootstrap stabilization,
61 * dependency initialization, or throttling requirements during application startup.
62 *
63 * @param bootDelay true to enforce an initial structural delay prior to thread execution;
64 * false for immediate background execution.
65 */
66 void runInBackground( boolean bootDelay );
67
68 /**
69 * Handles the configuration update for the application's operating system autostart behavior.
70 * <br>
71 * This method is triggered upon user interaction with the global autostart controls. It delegates
72 * the registration or removal of the application's boot-time execution hooks to the system
73 * integration layer, enabling the application to load minimized during system startup.
74 *
75 * @param autostart {@code true} to register the application for automatic launch on system boot;
76 * {@code false} to remove the autostart registration hook
77 */
78 void handleAutostart( boolean autostart );
79
80 /**
81 * Handles switching between different primary view layers within the main viewport.
82 *
83 * @param state The target structural navigation layer.
84 */
85 void handleNavigate( Gui.ViewState state );
86
87 /**
88 * Handles the creation and append workflow for a new managed task synchronization context instance.
89 */
90 void handleCreateNewJob();
91
92 /**
93 * Triggers the specialized configuration context dialog to change a job instance identification label.
94 *
95 * @param job The source configuration instance payload.
96 */
97 void handleRenameJob( SyncJobContext job );
98
99 /**
100 * Creates an independent copy of the currently selected task parameters profile mapping.
101 *
102 * @param job The source configuration instance payload.
103 */
104 void handleDuplicateJob( SyncJobContext job );
105
106 /**
107 * Triggers a destructive purging routine to eliminate identified duplicate entities
108 * within the scope of the given synchronization task context.
109 * Mutates the active memory allocation state and immediately persists structural changes.
110 *
111 * @param job The specific synchronization runtime context targeting duplicate remediation.
112 */
113 void deleteSelectedDuplicates( SyncJobContext job );
114
115 /**
116 * Permanently removes a task entity context from the global orchestrator matrix tracking layer.
117 *
118 * @param job The target configuration instance to wipe.
119 */
120 void handleDeleteJob( SyncJobContext job );
121
122 /**
123 * Coordinates and processes drag-and-drop reordering requests originating from the job list.
124 * Acts as the bridge to pass index mutations from the view architecture back to the
125 * underlying sequential model registries.
126 *
127 * @param thisIdx The destination target index where the dragged element is dropped.
128 * @param draggedIdx The original source index where the drag gesture was initiated.
129 */
130 void handleDragJob( int thisIdx, int draggedIdx );
131
132 /**
133 * Initiates execution of processing operations based on active configuration parameters.
134 *
135 * @param job The active task configuration processing target.
136 */
137 void handleExecuteTask( SyncJobContext job );
138
139 /**
140 * Stop execution of processing operations based on active configuration parameters.
141 *
142 * @param job The active task configuration processing target.
143 */
144 void handleStopTask( SyncJobContext job );
145
146 /**
147 * Commits altered orchestration state variables using the encapsulated properties entity carrier.
148 *
149 * @param targetTheme Visual presentation theme strategy selection.
150 */
151 void handleSaveSettings( AppTheme targetTheme );
152 }