com.pekinsoft.spi.ModuleControl Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ServiceProviders Show documentation
An API that allows for dynamic application features and loose coupling.
The newest version!
/*
 * Copyright (C) 2022 PekinSOFT Systems
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see .
 * 
 * *****************************************************************************
 *  Project    :   NTOS_Project
 *  Class      :   ModuleControl.java
 *  Author     :   Sean Carrick
 *  Created    :   Sep 18, 2022
 *  Modified   :   Sep 18, 2022
 *  
 *  Purpose: See class JavaDoc for explanation
 *  
 *  Revision History:
 *  
 *  WHEN          BY                   REASON
 *  ------------  -------------------  -----------------------------------------
 *  Sep 18, 2022  Sean Carrick         Initial creation.
 * *****************************************************************************
 */

package com.pekinsoft.spi;

/**
 * The {@code ModuleControl} interface provides methods for modules to use to
 * control their windows, initialization, destruction, activation, and 
 * deactivation.
 * 
 * The {@link #activate() activate} method allows for modules to perform
 * any actions that are necessary when the module is activated, such as database
 * configuration or other configuration for the module to be ready to be used.
 * 
 * The {@link #deactivate() deactivate} method allows for modules to
 * perform any actions that may be required if the user deactivates the module's
 * feature(s).
 * 
 * The {@link #initialize() initialize} method allows for modules to 
 * perform any initialization required when the application is starting and the
 * module was activated when the application last shut down. These actions could
 * include restoring previously saved preferences, etc.
 * 
 * The {@link #shutdown() shutdown} method allows for modules to save any
 * preferences they need upon application exit. This allows for the module to be
 * sure that when the application is started next time, any settings the user
 * may have modified will be the same as the last time the application was used.
 * 
 *
 * @author Sean Carrick <sean at pekinsoft dot com>
 * 
 * @version 1.3
 * @since 1.0
 */
public interface ModuleControl {
    
    /**
     * Allows for the module to restore any settings that were saved prior. This
     * method, while restoring saved settings, should provide valid default 
     * values for those settings in case this is the first time the module has
     * been started.
     * 
     * If this module provides windows that are opened by default on the initial
     * use of the module, this method should provide a means of making sure that
     * those default windows do not open if the user had them closed when the
     * application last exited.
     */
    public void initialize();
    
    /**
     * Allows for the module to save any settings that the user may have changed.
     * This method is useful for providing a quality user experience for the
     * overall application and the use of the module's features.
     * 
     * This method should take into account any of its windows that were open at
     * the time the application last exited, so that those windows may be reopened
     * upon application startup. If this module provides default windows that
     * are opened the first time the module is initialized, but the user has 
     * closed those windows at the last application exit, then this method should
     * save that information as well.
     */
    public void shutdown();
    
    /**
     * May be overridden to restore any windows in the module that were visible
     * when the controlling {@code org.jdesktop.application.Application
     * Application} last shut down. These windows should have been stored as
     * being open in the {@link #shutdown() shutdown} method of the module.
     * 
     * *The default implementation does nothing.*
     */
    public default void restore() {}
    
    /**
     * Allows for special configuration to take place when the module is 
     * activated, if the enclosing application provides a means by which the
     * user is able to activate and deactivate features.
     * 
     * This method is also handy to establish any settings keys that are
     * required by the module.
     * 
     * *The default implementation does nothing.*
     */
    public default void activate(){}
    
    /**
     * Allows for special configuration to take place when the module is 
     * deactivated, if the enclosing application provides a means by which the
     * user is able to activate and deactivate features.
     * 
     * This method is also handy to establish any settings values that are
     * required by the module.
     * 
     * *The default implementation does nothing.*
     */
    public default void deactivate(){}

}