com.lf.commons.model

Class ApplicationModel

java.lang.Object

com.lf.commons.model.ApplicationModel

All Implemented Interfaces:

LookAndFeelListener

public abstract class ApplicationModel
extends java.lang.Object
implements LookAndFeelListener

Manager class for application models.

Normally applications provide s special set of settings which the user can manipulate directly or which are set in the background like window positions et cetera. These settings can be stored to disk (or database, server, ...) as configuration files in properties or XML format. Applications also need other kinds of resources to be manipulated at runtime like caches, indexes, and images which need to be stored in binary formats. This model manages all kinds of resources for an application that can be stored persistently as files. The resources and their handlers must be registered and will then be automatically stored to disk (or database, server, ...) if the application is closed and then restored the next time it is started again.

The model uses one special configuration directory on the local system normally located in the user's home directory like C:/Dokumente und Einstellungen/user1/.digester. All registered resources are written to this directory which can easily be packaged as ZIP file for storage in a database or on a configuration server. From the security point of view only registered resources are stored, unknown files or directories are not recognized so that illegal files like porn or hacked software cannot be stored by the model.

Normally resources are stored on the local computer and restored the next time the application is started. If available the compressed or encrypted resource archive could be stored in a JDBC database or on a public configuration server as well. This allows users to share their settings with other users or with other application instances installed on different computers. This is real "Configure once, use everywhere". Since application settings can be classified into multiple categories like user specific, machine specific, shared, global, et cetera, the resource handlers must reflect the different types of settings. Some kinds of settings may be shared between different computers, some may not. Machine specific settings like paths in the local file system cannot be shared with other computers while user specific settings like an IMAP server can.

Modern applications normally use a more or less huge set of parameters and new application versions should convert the settings of the older versions to run. So the model and the handlers must provide a specific model version management which turns out to be quite application specific but can be supported by some standardized methods. The local directory is necessary as safe data store when the network connection breaks down. If the network is reachable again the application can then save a copy for backup or sharing purposes on the server.

Some directories and files are reserved and cannot be used for normal registration:

/admin Administrative files like file maps, indexes etc., private access /config Application configuration files /temp Temporary files, deleted on application exit, not stored persistently

TODO: Deploy resource files in a later version, here we use hard-coded files and directories TODO: since we only have two resource files at the moment (license and runtime configuration).

Since:

1.6

Version:

$Revision: 1.37 $, $Date: 2012/12/28 11:44:25 $

Author:

Axel Schwolow

Field Summary

Fields

Modifier and Type	Field and Description
protected java.io.File	adminDir Local directory to use for storage of administrative files.
protected java.io.File	baseDir Local directory to use for storage of configuration.
protected java.util.Hashtable<java.lang.String,ConfigurableUnit>	cacheConfigurablesByID Shared cache for configurable units, key is unique identifier (application specific).
protected java.util.Hashtable<java.lang.String,OptionsUnit>	cacheOptionUnitsByID Shared cache for option units, key is unique identifier (application specific).
protected java.util.Hashtable<java.lang.String,ResourceFile>	cacheResourceByID Shared cache for model resources, key is unique identifier (package + name).
protected Configuration	config Runtime configuration to store units persistently.
protected java.io.File	configDir Local directory to use for storage of configuration files.
protected java.io.File	configFile Stores the application configuration.
protected java.io.File	dataSourceDir Local directory to use for storage of data source persistence files.
protected boolean	firstStart Is the application started the first time (no configuration found)?
protected java.lang.String	format The current file compression algorithm, default is FORMAT_UNCOMPRESSED.
static java.lang.String	FORMAT_DEFLATED Resource files shall be stored DEFLATED.
static java.lang.String	FORMAT_GZIPPED Resource files shall be stored GZIPped.
static java.lang.String	FORMAT_UNCOMPRESSED Resource files shall be stored with no compression.
static java.lang.String	SUPPORT_ATTACHMENT Represents a category for SupportDataDialog.
static java.lang.String	SUPPORT_LICENSE Represents a category for SupportDataDialog.
static java.lang.String	SUPPORT_LOG Represents a category for SupportDataDialog.
static java.lang.String	SUPPORT_MESSAGE Represents a category for SupportDataDialog.
static java.lang.String	SUPPORT_SCREENSHOT Represents a category for SupportDataDialog.
static java.lang.String	SUPPORT_STATUS Represents a category for SupportDataDialog.
protected java.io.File	tempDir Local directory to use for storage of temporary files.

Constructor Summary

Constructors

Constructor and Description
ApplicationModel() Constructor method for i18n purposes only.
ApplicationModel(java.io.File basedir, java.lang.String configfile) Constructor method receiving the local configuration directory.

Method Summary

Methods

Modifier and Type	Method and Description
ModelConfig	checkZIP(java.io.File target) Checks the given target archive and provides the configuration descriptor if available.
void	clearTempDirectory(boolean onexit) Removes all files and directories from the temporary directory.
java.lang.String	exportToZIP(java.io.File target, java.lang.String ignored, DeployProps version, boolean store) Creates a compressed ZIP archive with the current configuration files and directories.
protected void	finalize() Cares for proper cleanup after releasing the object.
abstract SuffixFilter[]	getAllSuffixFilters() Convenience method to get all available file filters.
java.io.File	getConfigFile() Provides the configuration file for persistent storage.
ConfigurableUnit	getConfigurable(java.lang.String id) Gets the desired unit from the internal cache if available.
Configuration	getConfiguration() Provides the configuration instance for persistent storage.
java.io.File	getDataSourceDirectory() Provides the directory for data source persistence files.
abstract Configuration	getDefaultValues() Provides the default values for this model.
OptionsUnit	getOptionsUnit(java.lang.String id) Gets the desired options unit from the internal cache if available.
java.lang.String	getOptionsUnitID(java.lang.Class clazz) Gets the unique identifier of the desired options unit from the internal cache if available.
ResourceFile	getResource(java.lang.String id) Gets the desired resource from the internal cache if available.
abstract SuffixFilter	getSuffixFilter(java.lang.String filterid) Convenience method to get a certain file filter.
java.io.File	getTempDirectory() Provides the directory for temporary files.
boolean	hasConfigurable(ConfigurableUnit unit) Is the given unit identifier currently managed by the model?
boolean	hasConfigurable(java.lang.String id) Is the given unit identifier currently managed by the model?
boolean	hasOptionsUnit(OptionsUnit unit) Is the given options unit identifier currently managed by the model?
boolean	hasOptionsUnit(java.lang.String id) Is the given options unit identifier currently managed by the model?
boolean	hasResource(ResourceFile resource) Is the given resource currently managed by the model?
boolean	hasResource(java.lang.String id) Is the given resource identifier currently managed by the model?
boolean	isFirstStart() Checks if the application is started the first time (configuration does not exist).
protected abstract void	loadDefaultValues() Populates the internal cache with default values (overridden by subclasses).
protected void	loadOverrideValues() Populates the internal cache with override values after the file values have been loaded.
void	lookAndFeelChanged(java.lang.String plaf, java.lang.String theme) Reacts on changes of the look & feel performed by the manager.
void	registerConfigurable(java.lang.String id, ConfigurableUnit unit) Registers a configurable unit to be managed.
void	registerOptionsUnit(java.lang.String id, OptionsUnit unit) Adds a new options unit to the internal cache.
void	registerResource(ResourceFile resource) Registers a resource to be managed.
int	removeConfigurableVars(ConfigurableUnit unit) Removes all variable/value pairs beginning with the id prefix from the configuration.
int	removeConfigurableVars(java.lang.String id) Removes all variable/value pairs beginning with the id prefix from the configuration.
boolean	storeAll() Stores all managed configuration units persistently.
void	unregisterConfigurable(ConfigurableUnit unit) Removes the unit from the internal cache if available.
void	unregisterConfigurable(ConfigurableUnit unit, boolean store) Removes the unit from the internal cache if available.
void	unregisterConfigurable(java.lang.String id) Removes the unit from the internal cache if available.
void	unregisterConfigurable(java.lang.String id, boolean store) Removes the unit from the internal cache if available.
void	unregisterOptionsUnit(OptionsUnit unit) Removes the options unit from the internal cache if available.
void	unregisterOptionsUnit(OptionsUnit unit, boolean store) Removes the options unit from the internal cache if available.
void	unregisterOptionsUnit(java.lang.String id) Removes the options unit from the internal cache if available.
void	unregisterOptionsUnit(java.lang.String id, boolean store) Removes the options unit from the internal cache if available.
void	unregisterResource(ResourceFile resource) Removes the resource from the internal cache if available.
void	unregisterResource(java.lang.String id) Removes the resource from the internal cache if available.
void	updateComponentTreeUI() The (hidden) components should be refreshed by SwingUtilities.updateComponentTreeUI().

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FORMAT_UNCOMPRESSED

public static final java.lang.String FORMAT_UNCOMPRESSED

Resource files shall be stored with no compression.

See Also:

Constant Field Values

FORMAT_GZIPPED

public static final java.lang.String FORMAT_GZIPPED

Resource files shall be stored GZIPped.

See Also:

Constant Field Values

FORMAT_DEFLATED

public static final java.lang.String FORMAT_DEFLATED

Resource files shall be stored DEFLATED.

See Also:

Constant Field Values

SUPPORT_MESSAGE

public static final java.lang.String SUPPORT_MESSAGE

Represents a category for SupportDataDialog.

See Also:

Constant Field Values

SUPPORT_ATTACHMENT

public static final java.lang.String SUPPORT_ATTACHMENT

Represents a category for SupportDataDialog.

See Also:

Constant Field Values

SUPPORT_LICENSE

public static final java.lang.String SUPPORT_LICENSE

Represents a category for SupportDataDialog.

See Also:

Constant Field Values

SUPPORT_LOG

public static final java.lang.String SUPPORT_LOG

Represents a category for SupportDataDialog.

See Also:

Constant Field Values

SUPPORT_STATUS

public static final java.lang.String SUPPORT_STATUS

Represents a category for SupportDataDialog.

See Also:

Constant Field Values

SUPPORT_SCREENSHOT

public static final java.lang.String SUPPORT_SCREENSHOT

Represents a category for SupportDataDialog.

See Also:

Constant Field Values

baseDir

protected java.io.File baseDir

Local directory to use for storage of configuration.

adminDir

protected java.io.File adminDir

Local directory to use for storage of administrative files.

configDir

protected java.io.File configDir

Local directory to use for storage of configuration files.

configFile

protected java.io.File configFile

Stores the application configuration.

tempDir

protected java.io.File tempDir

Local directory to use for storage of temporary files.

dataSourceDir

protected java.io.File dataSourceDir

Local directory to use for storage of data source persistence files.

format

protected java.lang.String format

The current file compression algorithm, default is FORMAT_UNCOMPRESSED.

cacheResourceByID

protected java.util.Hashtable<java.lang.String,ResourceFile> cacheResourceByID

Shared cache for model resources, key is unique identifier (package + name).

cacheConfigurablesByID

protected java.util.Hashtable<java.lang.String,ConfigurableUnit> cacheConfigurablesByID

Shared cache for configurable units, key is unique identifier (application specific).

cacheOptionUnitsByID

protected java.util.Hashtable<java.lang.String,OptionsUnit> cacheOptionUnitsByID

Shared cache for option units, key is unique identifier (application specific).

config

protected Configuration config

Runtime configuration to store units persistently.

firstStart

protected boolean firstStart

Is the application started the first time (no configuration found)?

Constructor Detail

ApplicationModel

public ApplicationModel()
                 throws java.lang.InstantiationException

Constructor method for i18n purposes only.

Can only be used if beans design time is set (e.g. by external tools like the I18NExtractor).

Throws:

java.lang.InstantiationException - Error indication

Since:

1.6

ApplicationModel

public ApplicationModel(java.io.File basedir,
                java.lang.String configfile)
                 throws java.lang.IllegalArgumentException

Constructor method receiving the local configuration directory.

The normal way to handle configurations is to access the local file system primarily. This is fast and safe. Additionally it can be useful to save a copy of the configuration directory on some kind of server, either for backup or sharing purposes.

Parameters:

basedir - The local directory to use

configfile - The short name of the configuration file

Throws:

java.lang.NullPointerException - If parameters are null

java.lang.IllegalArgumentException - If parameters are invalid (e.g. id already in use)

Since:

1.6

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Cares for proper cleanup after releasing the object.

Especially the containers are emptied properly in order to help the garbage collecting.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

Since:

1.6

registerResource

public void registerResource(ResourceFile resource)
                      throws java.lang.IllegalArgumentException

Registers a resource to be managed.

If not already in use the resource is placed at the desired location relative to the application configuration directory. If not available another path is chosen since the resources are not aware of their location since loading and storing is done by using byte-based streams.

Parameters:

resource - The resource to be added

Throws:

java.lang.NullPointerException - If parameters are null

java.lang.IllegalArgumentException - If parameters are invalid (e.g. id already in use)

Since:

1.6

getResource

public ResourceFile getResource(java.lang.String id)

Gets the desired resource from the internal cache if available.

Parameters:

id - The unique identifier (package + name)

Returns:

The resource file object, maybe null

Since:

1.6

hasResource

public boolean hasResource(java.lang.String id)

Is the given resource identifier currently managed by the model?

Parameters:

id - The unique identifier (package + name)

Returns:

Currently registered?

Since:

1.6

hasResource

public boolean hasResource(ResourceFile resource)

Is the given resource currently managed by the model?

Parameters:

resource - The resource to be checked

Returns:

Currently registered?

Since:

1.6

unregisterResource

public void unregisterResource(ResourceFile resource)

Removes the resource from the internal cache if available.

Parameters:

resource - The resource to be removed

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

unregisterResource

public void unregisterResource(java.lang.String id)

Removes the resource from the internal cache if available.

Parameters:

id - The unique identifier (package + name)

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

registerConfigurable

public void registerConfigurable(java.lang.String id,
                        ConfigurableUnit unit)

Registers a configurable unit to be managed.

Configurable units can be arbitrary objects like dialogs (size and position), frames, GUI components, tasks (schedule configuration) etc. Each unit is identified with a unique id that should be generated or managed by the application.

If a configurable unit is registered successfully then its configure() method is called immediately in order to load it with configuration data. If no values are available (for instance if the application is started the first time) then the default configuration should be used. So the unit must check whether there are valid values available or not.

Parameters:

id - The unique id

unit - The configurable unit to be added

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

getConfigurable

public ConfigurableUnit getConfigurable(java.lang.String id)

Gets the desired unit from the internal cache if available.

Parameters:

id - The unique identifier

Returns:

The configurable unit, maybe null

Since:

1.6

hasConfigurable

public boolean hasConfigurable(java.lang.String id)

Is the given unit identifier currently managed by the model?

Parameters:

id - The unique identifier

Returns:

Currently registered?

Since:

1.6

hasConfigurable

public boolean hasConfigurable(ConfigurableUnit unit)

Is the given unit identifier currently managed by the model?

Parameters:

unit - The unit to be checked

Returns:

Currently registered?

Since:

1.6

unregisterConfigurable

public void unregisterConfigurable(ConfigurableUnit unit)

Removes the unit from the internal cache if available.

Parameters:

unit - The unit to be removed

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

unregisterConfigurable

public void unregisterConfigurable(java.lang.String id)

Removes the unit from the internal cache if available.

Parameters:

id - The unique identifier

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

unregisterConfigurable

public void unregisterConfigurable(ConfigurableUnit unit,
                          boolean store)

Removes the unit from the internal cache if available.

Parameters:

unit - The unit to be removed

store - Store the unit after removal?

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

unregisterConfigurable

public void unregisterConfigurable(java.lang.String id,
                          boolean store)

Removes the unit from the internal cache if available.

Parameters:

id - The unique identifier

store - Store the unit after removal?

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

removeConfigurableVars

public int removeConfigurableVars(ConfigurableUnit unit)

Removes all variable/value pairs beginning with the id prefix from the configuration.

Remember that the given unit must already be registered to determine the identifier.

Parameters:

unit - The unit to remove variables

Returns:

Number of removed variables

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

removeConfigurableVars

public int removeConfigurableVars(java.lang.String id)

Removes all variable/value pairs beginning with the id prefix from the configuration.

Parameters:

id - The unique identifier

Returns:

Number of removed variables

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

getConfiguration

public Configuration getConfiguration()

Provides the configuration instance for persistent storage.

Returns:

The configuration instance

Since:

1.6

getConfigFile

public java.io.File getConfigFile()

Provides the configuration file for persistent storage.

Returns:

The configuration file

Since:

1.6

getTempDirectory

public java.io.File getTempDirectory()

Provides the directory for temporary files.

No registration is needed for writing files in the temp directory. If new files are created the methods should make sure not to overwrite existing files by using unique file names perhaps beginning with the full class identifiers of the accessing class. Temporary files are automatically removed when the application terminates and if it is started again. Temporary files are never stored as part of server-based settings. If temporary files are needed for the next application run consider registration of a dedicated configuration directory instead. Help keeping the configuration footprint small temporary files and directories should be deleted when not needed any longer.

Returns:

The directory for temporary files

Since:

1.6

clearTempDirectory

public void clearTempDirectory(boolean onexit)

Removes all files and directories from the temporary directory.

This should be run when the application terminates and possibly when it starts again to make sure that no unnecessary files are handled. Although the temporary files are not stored as part of server-based settings modern applications may produce many files consuming a large amount of disk space.

Parameters:

onexit - Delete the files "on exit"?

Since:

1.6

getDataSourceDirectory

public java.io.File getDataSourceDirectory()

Provides the directory for data source persistence files.

Returns:

The directory for data sources

Since:

1.6

storeAll

public boolean storeAll()

Stores all managed configuration units persistently.

Returns:

Did it work?

Since:

1.6

exportToZIP

public java.lang.String exportToZIP(java.io.File target,
                           java.lang.String ignored,
                           DeployProps version,
                           boolean store)

Creates a compressed ZIP archive with the current configuration files and directories.

The storeAll() method is called first in order to get the current settings on disk. The central descriptor holding the import information is the 'admin/config.xml' file based on an XML format which is automatically added to the archive.

Parameters:

target - The target archive

ignored - The regex filter for targets to be ignored, maybe null

version - The application version infos

store - Store units before export?

Returns:

Error message or null on success

Since:

1.6

checkZIP

public ModelConfig checkZIP(java.io.File target)

Checks the given target archive and provides the configuration descriptor if available.

Parameters:

target - The target archive

Returns:

Configuration descriptor, null indicates error

Since:

1.6

isFirstStart

public boolean isFirstStart()

Checks if the application is started the first time (configuration does not exist).

Returns:

Started the first time?

Since:

1.6

getOptionsUnit

public OptionsUnit getOptionsUnit(java.lang.String id)

Gets the desired options unit from the internal cache if available.

Parameters:

id - The unique identifier

Returns:

The configurable unit, maybe null

Since:

1.6

getOptionsUnitID

public java.lang.String getOptionsUnitID(java.lang.Class clazz)

Gets the unique identifier of the desired options unit from the internal cache if available.

Parameters:

clazz - The option unit class

Returns:

The unit identifier, maybe null

Since:

1.6

hasOptionsUnit

public boolean hasOptionsUnit(java.lang.String id)

Is the given options unit identifier currently managed by the model?

Parameters:

id - The unique identifier

Returns:

Currently registered?

Since:

1.6

hasOptionsUnit

public boolean hasOptionsUnit(OptionsUnit unit)

Is the given options unit identifier currently managed by the model?

Parameters:

unit - The unit to be checked

Returns:

Currently registered?

Since:

1.6

registerOptionsUnit

public void registerOptionsUnit(java.lang.String id,
                       OptionsUnit unit)

Adds a new options unit to the internal cache.

Parameters:

id - The unique identifier

unit - The unit to be added

Throws:

java.lang.NullPointerException - If parameters are null

java.lang.IllegalArgumentException - If parameters are invalid (e.g. id already in use)

Since:

1.6

unregisterOptionsUnit

public void unregisterOptionsUnit(OptionsUnit unit)

Removes the options unit from the internal cache if available.

Parameters:

unit - The unit to be removed

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

unregisterOptionsUnit

public void unregisterOptionsUnit(java.lang.String id)

Removes the options unit from the internal cache if available.

Parameters:

id - The unique identifier

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

unregisterOptionsUnit

public void unregisterOptionsUnit(OptionsUnit unit,
                         boolean store)

Removes the options unit from the internal cache if available.

Parameters:

unit - The unit to be removed

store - Store the unit after removal?

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

unregisterOptionsUnit

public void unregisterOptionsUnit(java.lang.String id,
                         boolean store)

Removes the options unit from the internal cache if available.

Parameters:

id - The unique identifier

store - Store the unit after removal?

Throws:

java.lang.NullPointerException - If parameters are null

Since:

1.6

lookAndFeelChanged

public void lookAndFeelChanged(java.lang.String plaf,
                      java.lang.String theme)

Reacts on changes of the look & feel performed by the manager.

Since the options units are normally created in the background without adding them to a valid container, we need to propagate look & feel changes properly.

Specified by:

lookAndFeelChanged in interface LookAndFeelListener

Parameters:

plaf - The current look & feel in fully qualified notation

theme - The configuration of the specific look & feel, may be null

Since:

1.6

updateComponentTreeUI

public void updateComponentTreeUI()

The (hidden) components should be refreshed by SwingUtilities.updateComponentTreeUI().

May be called by the manager if font sizes, colors etc. have been changed.

Specified by:

updateComponentTreeUI in interface LookAndFeelListener

Since:

1.6

loadOverrideValues

protected void loadOverrideValues()

Populates the internal cache with override values after the file values have been loaded.

Since:

1.6

loadDefaultValues

protected abstract void loadDefaultValues()

Populates the internal cache with default values (overridden by subclasses).

Since:

1.6

getDefaultValues

public abstract Configuration getDefaultValues()

Provides the default values for this model.

Returns:

The container with defaults

Since:

1.6

getSuffixFilter

public abstract SuffixFilter getSuffixFilter(java.lang.String filterid)

Convenience method to get a certain file filter.

Parameters:

filterid - The filter identifier

Returns:

The filter, may be null

Since:

1.6

getAllSuffixFilters

public abstract SuffixFilter[] getAllSuffixFilters()

Convenience method to get all available file filters.

Returns:

The filters, may be null or have zero-length

Since:

1.6