Module is.codion.swing.framework.ui

Package is.codion.swing.framework.ui

Class EntityApplication<M extends SwingEntityApplicationModel,P extends EntityApplicationPanel<M>>

java.lang.Object

is.codion.swing.framework.ui.EntityApplication<M,P>

Type Parameters:

M - the application model type

P - the application panel type

public final class EntityApplication<M extends SwingEntityApplicationModel,P extends EntityApplicationPanel<M>>
extends Object

Builds and starts an application.

See Also:

• builder(Class, Class)
• start()

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	EntityApplication.DomainStep<M extends SwingEntityApplicationModel,P extends EntityApplicationPanel<M>>	Specifies the application domain model type.

Field Summary

Fields

Modifier and Type	Field	Description
static final PropertyValue<Boolean>	CONNECTION_INFO_UPPER_CASE	Specifies whether the connection information displayed in the frame title is automatically converted to upper case.
static final PropertyValue<Boolean>	SAVE_DEFAULT_USERNAME	Specifies whether the client saves the last successful login username, which is then displayed as the default username the next time the application is started Value type: Boolean Default value: true
static final PropertyValue<Boolean>	STARTUP_DIALOG	Specifies whether a startup dialog should be shown Value type: Boolean Default value: true
static final PropertyValue<String>	USER	Specifies the user for logging into the application on the form user:password.

Method Summary

Modifier and Type	Method	Description
static <M extends SwingEntityApplicationModel, P extends EntityApplicationPanel<M>> EntityApplication.DomainStep<M,P>	builder(Class<M> applicationModelClass, Class<P> applicationPanelClass)
EntityApplication<M,P>	clientType(String clientType)	Sets the client type of the connection the application creates, identifying the application to a server, which may choose its authenticator, session contexts and idle connection timeout by it.
EntityApplication<M,P>	connection(EntityConnection connection)	Overrides connection(Function).
EntityApplication<M,P>	connection(Function<User,EntityConnection> connection)	Note that the login dialog relies on the given function connecting eagerly, failing when given invalid credentials or an unreachable server.
EntityApplication<M,P>	connectionInfoUpperCase(boolean connectionInfoUpperCase)
EntityApplication<M,P>	defaultFrameSize(@Nullable Dimension defaultFrameSize)
EntityApplication<M,P>	defaultLookAndFeel(Class<? extends LookAndFeel> defaultLookAndFeelClass)	Sets the default look and feel class, used in case no look and feel settings are found in user preferences.
EntityApplication<M,P>	defaultLookAndFeel(String defaultLookAndFeelClassName)	Sets the default look and feel classname, used in case no look and feel settings are found in user preferences.
EntityApplication<M,P>	defaultUser(@Nullable User defaultUser)
EntityApplication<M,P>	displayFrame(boolean displayFrame)
EntityApplication<M,P>	frame(Supplier<JFrame> frame)
EntityApplication<M,P>	frameSize(@Nullable Dimension frameSize)
EntityApplication<M,P>	frameTitle(Observable<String> frameTitle)	For a dynamic frame title.
EntityApplication<M,P>	frameTitle(String frameTitle)
EntityApplication<M,P>	icon(ImageIcon icon)
EntityApplication<M,P>	loginPanelSouthComponent(Supplier<JComponent> loginPanelSouthComponentSupplier)	Note that this does not apply when a custom user(Supplier) has been specified.
EntityApplication<M,P>	lookAndFeel(Class<? extends LookAndFeel> lookAndFeelClass)	Sets the look and feel class, overrides any look and feel settings found in user preferences.
EntityApplication<M,P>	lookAndFeel(String lookAndFeelClassName)	Sets the look and feel classname, overrides any look and feel settings found in user preferences.
EntityApplication<M,P>	mainMenu(boolean mainMenu)
EntityApplication<M,P>	maximizeFrame(boolean maximizeFrame)
EntityApplication<M,P>	model(BiFunction<EntityConnection,User,M> model)	The application model factory, receiving the connection and the application user, the one logged in, for the model to hold, see EntityApplicationModel.user().
EntityApplication<M,P>	model(Function<EntityConnection,M> model)
EntityApplication<M,P>	name(String name)	Sets the application name, shown to the user: in the titles of the login dialog and the startup dialog, and in the frame's default title, which frameTitle(String) replaces.
EntityApplication<M,P>	onStarted(@Nullable Consumer<P> onStarted)
EntityApplication<M,P>	onStarting(@Nullable Runnable onStarting)	Runs as the application is starting, but after Look and Feel initialization.
EntityApplication<M,P>	panel(Function<M,P> panel)
EntityApplication<M,P>	preferences(Preferences preferences)	The Preferences instance the application-level preferences (frame size, look and feel, default user, scaling) are read from at start() and, on exit, written to — in place of the default file-based user preferences.
EntityApplication<M,P>	saveDefaultUsername(boolean saveDefaultUsername)
void	start()	Starts the application on the Event Dispatch Thread.
void	start(boolean onEventDispatchThread)	Starts the application.
EntityApplication<M,P>	startupDialog(boolean startupDialog)
EntityApplication<M,P>	uncaughtExceptionHandler(boolean uncaughtExceptionHandler)	Specifies whether to set the default uncaught exception handler when starting the application, true by default.
EntityApplication<M,P>	user(@Nullable User user)	The application user, the one logging in, propagated to connection(Function) and the model factory.
EntityApplication<M,P>	user(Function<@Nullable User,Supplier<User>> userSupplier)	Supplies the application user, the one logging in, propagated to connection(Function) and the model factory.
EntityApplication<M,P>	user(Supplier<User> userSupplier)	Supplies the application user, the one logging in, propagated to connection(Function) and the model factory.
EntityApplication<M,P>	version(Version version)	Sets the application version, shown in the frame title and the About panel.

Methods inherited from class java.lang.Object

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

Field Details

USER

public static final PropertyValue<String> USER

Specifies the user for logging into the application on the form user:password. If one is specified no login dialog is presented.

Initialized with the value of the CODION_CLIENT_USER environment variable.

Warning: System properties are visible in process listings. Use only for development/testing. In production, use secure credential management.

• Value type: String
• Default value: System.getenv("CODION_CLIENT_USER")

See Also:

• User.parse(String)

SAVE_DEFAULT_USERNAME

public static final PropertyValue<Boolean> SAVE_DEFAULT_USERNAME

Specifies whether the client saves the last successful login username, which is then displayed as the default username the next time the application is started

• Value type: Boolean
• Default value: true

STARTUP_DIALOG

public static final PropertyValue<Boolean> STARTUP_DIALOG

Specifies whether a startup dialog should be shown

• Value type: Boolean
• Default value: true

CONNECTION_INFO_UPPER_CASE

public static final PropertyValue<Boolean> CONNECTION_INFO_UPPER_CASE

Specifies whether the connection information displayed in the frame title is automatically converted to upper case.

If not, the username as input via the login dialog is used along with the connection description as provided by the underlying EntityConnection. This may result in "Scott@DevDb" or "scott@DEVSERVER@hostname" instead of the default "SCOTT@DEVDB" or "SCOTT@DEVSERVER@HOSTNAME".

• Value type: Boolean
• Default value: true

Method Details

icon

public EntityApplication<M,P> icon(ImageIcon icon)

Parameters:

icon - the application icon

Returns:

this EntityApplication instance

defaultLookAndFeel

public EntityApplication<M,P> defaultLookAndFeel(Class<? extends LookAndFeel> defaultLookAndFeelClass)

Sets the default look and feel class, used in case no look and feel settings are found in user preferences.

Parameters:

defaultLookAndFeelClass - the default look and feel class

Returns:

this EntityApplication instance

See Also:

• LookAndFeelProvider

defaultLookAndFeel

public EntityApplication<M,P> defaultLookAndFeel(String defaultLookAndFeelClassName)

Sets the default look and feel classname, used in case no look and feel settings are found in user preferences.

Parameters:

defaultLookAndFeelClassName - the default look and feel classname

Returns:

this EntityApplication instance

See Also:

• LookAndFeelProvider

lookAndFeel

public EntityApplication<M,P> lookAndFeel(Class<? extends LookAndFeel> lookAndFeelClass)

Sets the look and feel class, overrides any look and feel settings found in user preferences.

Parameters:

lookAndFeelClass - the look and feel class

Returns:

this EntityApplication instance

See Also:

• LookAndFeelProvider

lookAndFeel

public EntityApplication<M,P> lookAndFeel(String lookAndFeelClassName)

Sets the look and feel classname, overrides any look and feel settings found in user preferences.

Parameters:

lookAndFeelClassName - the look and feel classname

Returns:

this EntityApplication instance

See Also:

• LookAndFeelProvider

name

public EntityApplication<M,P> name(String name)

Sets the application name, shown to the user: in the titles of the login dialog and the startup dialog, and in the frame's default title, which frameTitle(String) replaces.

DomainType.name() by default.

Parameters:

name - the application name

Returns:

this EntityApplication instance

Throws:

IllegalArgumentException - in case the name is empty

See Also:

• clientType(String)

clientType

public EntityApplication<M,P> clientType(String clientType)

Sets the client type of the connection the application creates, identifying the application to a server, which may choose its authenticator, session contexts and idle connection timeout by it. Not shown in the application, see name(String).

Applies only to the connection created by default, not to one given or created by a connection function, which sets its own.

DomainType.name() by default, as with EntityConnection.Builder.clientType(String).

Parameters:

clientType - the client type

Returns:

this EntityApplication instance

Throws:

IllegalArgumentException - in case the client type is empty

version

public EntityApplication<M,P> version(Version version)

Sets the application version, shown in the frame title and the About panel.

Also identifies the application version to a server, via EntityConnection.Builder.clientVersion(Version). This applies only to the connection created by default, not to one given or created by a connection function, which sets its own.

Parameters:

version - the application version

Returns:

this EntityApplication instance

model

public EntityApplication<M,P> model(Function<EntityConnection,M> model)

Parameters:

model - the application model factory, receiving the connection

Returns:

this EntityApplication instance

See Also:

• model(BiFunction)

model

public EntityApplication<M,P> model(BiFunction<EntityConnection,User,M> model)

The application model factory, receiving the connection and the application user, the one logged in, for the model to hold, see EntityApplicationModel.user().

The application user differs from the connection's user when the connection function connects as another user. With a connection given, no user is supplied and the application user is the connection's user.

Parameters:

model - the application model factory, receiving the connection and the application user

Returns:

this EntityApplication instance

panel

public EntityApplication<M,P> panel(Function<M,P> panel)

Parameters:

panel - the application panel factory

Returns:

this EntityApplication instance

defaultUser

public EntityApplication<M,P> defaultUser(@Nullable User defaultUser)

Parameters:

defaultUser - the default user credentials to display in a login dialog

Returns:

this EntityApplication instance

preferences

public EntityApplication<M,P> preferences(Preferences preferences)

The Preferences instance the application-level preferences (frame size, look and feel, default user, scaling) are read from at start() and, on exit, written to — in place of the default file-based user preferences. Any explicit builder call (e.g. frameSize(Dimension)) still takes precedence over a stored value.

This is the application-level half only; the model and its panels keep their own preferences (see the Preferences constructor of AbstractEntityApplicationModel). For a fully self-contained application (e.g. a test using JsonPreferences.jsonPreferences()), inject the same instance into both — here and via the model factory.

Parameters:

preferences - the preferences instance to use for the application-level preferences

Returns:

this EntityApplication instance

user

public EntityApplication<M,P> user(@Nullable User user)

The application user, the one logging in, propagated to connection(Function) and the model factory.

If this user is null, user(Supplier) is used to fetch a user.

Parameters:

user - the application user

Returns:

this EntityApplication instance

See Also:

• USER

user

public EntityApplication<M,P> user(Supplier<User> userSupplier)

Supplies the application user, the one logging in, propagated to connection(Function) and the model factory.

This may be via a login dialog or simply by returning a hardcoded instance.

Startup is silently cancelled in case the Supplier.get() throws a CancelException.

Parameters:

userSupplier - supplies the application user, for example via a login dialog

Returns:

this EntityApplication instance

user

public EntityApplication<M,P> user(Function<@Nullable User,Supplier<User>> userSupplier)

Supplies the application user, the one logging in, propagated to connection(Function) and the model factory.

This may be via a login dialog or simply by returning a hardcoded instance.

This function receives the default user set via defaultUser(User) or the one saved in application preferences, null if none is available.

Startup is silently cancelled in case the Supplier.get() throws a CancelException.

Parameters:

userSupplier - supplies the application user, for example via a login dialog

Returns:

this EntityApplication instance

saveDefaultUsername

public EntityApplication<M,P> saveDefaultUsername(boolean saveDefaultUsername)

Parameters:

saveDefaultUsername - true if the username should be saved in user preferences after a successful login

Returns:

this EntityApplication instance

frame

public EntityApplication<M,P> frame(Supplier<JFrame> frame)

Parameters:

frame - the supplies the frame to use

Returns:

this EntityApplication instance

frameTitle

public EntityApplication<M,P> frameTitle(String frameTitle)

Parameters:

frameTitle - the frame title

Returns:

this EntityApplication instance

frameTitle

public EntityApplication<M,P> frameTitle(Observable<String> frameTitle)

For a dynamic frame title.

Parameters:

frameTitle - the observable controlling the frame title

Returns:

this EntityApplication instance

connectionInfoUpperCase

public EntityApplication<M,P> connectionInfoUpperCase(boolean connectionInfoUpperCase)

Parameters:

connectionInfoUpperCase - specifies whether the connection information displayed in the frame title is automatically converted to upper case

Returns:

this EntityApplication instance

See Also:

• CONNECTION_INFO_UPPER_CASE

mainMenu

public EntityApplication<M,P> mainMenu(boolean mainMenu)

Parameters:

mainMenu - if true then a main menu is included

Returns:

this EntityApplication instance

maximizeFrame

public EntityApplication<M,P> maximizeFrame(boolean maximizeFrame)

Parameters:

maximizeFrame - specifies whether the frame should be maximized or use its preferred size

Returns:

this EntityApplication instance

displayFrame

public EntityApplication<M,P> displayFrame(boolean displayFrame)

Parameters:

displayFrame - specifies whether the frame should be displayed or left invisible

Returns:

this EntityApplication instance

uncaughtExceptionHandler

public EntityApplication<M,P> uncaughtExceptionHandler(boolean uncaughtExceptionHandler)

Specifies whether to set the default uncaught exception handler when starting the application, true by default.

Parameters:

uncaughtExceptionHandler - if true the default uncaught exception handler is set on application start

Returns:

this EntityApplication instance

See Also:

• Thread.setDefaultUncaughtExceptionHandler(Thread.UncaughtExceptionHandler)

startupDialog

public EntityApplication<M,P> startupDialog(boolean startupDialog)

Parameters:

startupDialog - if true then a progress dialog is displayed while the application is being initialized

Returns:

this EntityApplication instance

frameSize

public EntityApplication<M,P> frameSize(@Nullable Dimension frameSize)

Parameters:

frameSize - the frame size when not maximized

Returns:

this EntityApplication instance

defaultFrameSize

public EntityApplication<M,P> defaultFrameSize(@Nullable Dimension defaultFrameSize)

Parameters:

defaultFrameSize - the default frame size when no previous size is available in user preferences

Returns:

this EntityApplication instance

loginPanelSouthComponent

public EntityApplication<M,P> loginPanelSouthComponent(Supplier<JComponent> loginPanelSouthComponentSupplier)

Note that this does not apply when a custom user(Supplier) has been specified.

Parameters:

loginPanelSouthComponentSupplier - supplies the component to add to the BorderLayout.SOUTH position of the default login panel

Returns:

this EntityApplication instance

onStarting

public EntityApplication<M,P> onStarting(@Nullable Runnable onStarting)

Runs as the application is starting, but after Look and Feel initialization. Throw CancelException in order to cancel the application startup.

Parameters:

onStarting - run before the application is started

Returns:

this EntityApplication instance

onStarted

public EntityApplication<M,P> onStarted(@Nullable Consumer<P> onStarted)

Parameters:

onStarted - called after a successful application start

Returns:

this EntityApplication instance

connection

public EntityApplication<M,P> connection(EntityConnection connection)

Overrides connection(Function).

No user is then supplied, the connection's user being the application user.

Parameters:

connection - the connection for the application to use

Returns:

this EntityApplication instance

connection

public EntityApplication<M,P> connection(Function<User,EntityConnection> connection)

Note that the login dialog relies on the given function connecting eagerly, failing when given invalid credentials or an unreachable server. EntityConnection.builder() and the transport specific builders guarantee this, building establishes the connection - a function returning an unestablished hand-rolled EntityConnection would validate any credentials.

The function may connect as another user than the one it receives, the application user, a local database under a fixed user for example, the login meant for something else. The application user then reaches the model via model(BiFunction), and once the model holds it, it's the user shown in the frame title and saved as the default username, see EntityApplicationModel.user().

Parameters:

connection - provides the application connection, receives the user provided by user(Supplier)

Returns:

this EntityApplication instance

start

public void start()

Starts the application on the Event Dispatch Thread.

start

public void start(boolean onEventDispatchThread)

Starts the application.

Parameters:

onEventDispatchThread - if true then startup is performed on the Event Dispatch Thread

builder

public static <M extends SwingEntityApplicationModel,
P extends EntityApplicationPanel<M>>
EntityApplication.DomainStep<M,P> builder(Class<M> applicationModelClass,
 Class<P> applicationPanelClass)

Type Parameters:

M - the application model type

P - the application panel type

Parameters:

applicationModelClass - the application model class

applicationPanelClass - the application panel class

Returns:

a EntityApplication