oracle.ide.db.components

Class ComponentWrapper<T extends java.awt.Component>

java.lang.Object

oracle.ide.db.components.ComponentWrapper<T>

Type Parameters:

T - the type of wrapped component

Direct Known Subclasses:

oracle.ideimpl.db.components.AsynchronousComponentWrapper

public abstract class ComponentWrapper<T extends java.awt.Component>
extends java.lang.Object

A ComponentWrapper encapsulates a UI component that edits a single property on a given DBObject. The wrapper takes care of synchronizing the property value between the object and the UI so that changes in either are appropriately reflected in the other.

Since:

12

See Also:

ComponentFactory, ComponentContext

Constructor Summary

Constructors

Constructor and Description
ComponentWrapper(T activeComponent) Constructs a ComponentWrapper around the given Component.

Method Summary

Modifier and Type	Method and Description
void	addListener(java.beans.PropertyChangeListener listener) Registers the given PropertyChangeListener with this Component to be notifed when the value in the UI is changed.
void	addVetoListener(java.beans.VetoableChangeListener listener) Registers the given VetoableChangeListener with this Component to be notifed when the value in the UI is changed.
protected boolean	checkPropertyIsSupported() Called to determine whether the wrapper property is supported for the object in the current ComponentContext.
protected java.awt.Component	createComponentForLayout() Creates the Component that will be added to any layout for the given active component.
protected boolean	fireChangeEvent() This method should be called when the UI has been changed and the value from the UI should be committed to the underlying DBObject model.
protected void	fireVetoableChangeEvent() This method should be called when the UI has been changed and the value from the UI should be committed to the underlying DBObject model, but the commit is vetoable.
T	getActiveComponent() Gets the "active" Component from this wrapper.
java.awt.Component	getCellEditorComponent() If this ComponentWrapper is used within a JTable to provide edit capabilities for a cell this method is used to get the editor component.
java.awt.Component	getComponent() Gets the "layout" Component from this wrapper.
ComponentContext	getComponentContext() Gets the context that this ComponentWrapper was initialised with.
java.awt.Component	getDefaultFocusComponent() Gets the particular Component that is the focus of the property value.
protected java.awt.Component	getDefaultValidationComponent() By default setValidationStatus(java.util.Collection<oracle.javatools.db.validators.ValidationException>, oracle.ideimpl.db.validate.DBValidationHandler) will apply a status indication to the component returned by this component.
protected java.lang.Object	getExistingPropertyValue() Gets the existing property value from the underlying DBObject model (the updated object).
javax.swing.JLabel	getLabel() If the Component has a JLabel associated with it this returns the label.
protected java.util.logging.Logger	getLogger() Get the Logger to log messages to for this wrapper.
protected DBObject	getOriginalObject() Gets the original object that is being edited.
protected java.lang.Object	getOriginalPropertyValue() Gets the original property value from the underlying DBObject model (i.e.
java.lang.String	getPropertyDisplayName() Gets the displayable (translated) name for the property that this wrapper is editing.
protected PropertyHelper	getPropertyHelper() Gets a PropertyHelper instance that is cached for this editor.
java.lang.String	getPropertyName() Gets the name of the property that this wrapper is editing.
abstract java.lang.Object	getPropertyValue() Gets the value of the property as currently set in the UI Component e.g.
protected DBObjectProvider	getProvider() Gets the DBObjectProvider that the object being edited is from/for.
protected DBObject	getUpdatedObject() Gets the object that is being edited or created.
void	initialise(ComponentContext ctxt) Called once on create of each ComponentWrapper to initialise the DBObjectProvider, DBObject etc.
protected void	initialiseComponent() If any setup of the Component is needed after the provider/object are known override this method and implement there.
protected abstract void	initialiseComponentListener() Initialises a listener against the underlying Component that will call fireChangeEvent whenever the value in the UI is changed by the user.
boolean	isActive() Tests whether this ComponentWrapper is active (i.e.
boolean	isSupported() Is this property supported for the context DB Object
boolean	isVolatile() Tests whether this ComponentWrapper wrappers a property that is volatile i.e.
void	processComponent(boolean editable, boolean allowRecreate) Processes the underlying component by checking whether the property is supported and hiding or disabling the wrapped component accordingly.
boolean	refreshObject(DBObject refreshedObject) Refreshes this ComponentWrapper with a new updatedObject for its ComponentContext.
void	removeListener(java.beans.PropertyChangeListener listener) Removes a listener previously registered with addListener(java.beans.PropertyChangeListener)
void	removeVetoListener(java.beans.VetoableChangeListener listener) Removes a listener previously registered with addVetoListener(java.beans.VetoableChangeListener)
void	resetPropertyValue(java.lang.Object newValue) Convenience method to set the given value for the property we are wrapping on both the underlying DBObject, and in the underlying Component.
protected void	resourceComponent(oracle.ideimpl.db.DBUIResourceHelper resHelp) Sets up the resourcing of the component and its label (if one exists).
void	setActive(boolean active) Sets whether this ComponentWrapper is active - i.e.
protected void	setActiveImpl(boolean active) Called when a ComponentWrapper is activated/deactivated - typically onEntry/onExit of the owning panel.
void	setEnabled(boolean enabled) Sets the enabled state of the components within the wrapper.
void	setPropertyDisplayName(java.lang.String displayName) Sets the displayable (translated) name for the property that this wrapper is editing.
abstract void	setPropertyValue(java.lang.Object val) Sets the value of the property displayed in the UI.
void	setReadOnly(boolean readOnly) Sets the component to be read-only, such that any attempt to change its value will be ignored and reset.
protected void	setUIReadOnly(boolean readOnly) Subclasses may implement this method to make the UI readonly on request.
void	setValidationStatus(java.util.Collection<ValidationException> ves, oracle.ideimpl.db.validate.DBValidationHandler handler) Sets the validation status of the wrapped property value.
void	setVisible(boolean visible) Sets the visible state of the components within the wrapper.
protected void	showError(java.lang.String message) Shows an error message relating to the value of the wrapped Component to the user.

Methods inherited from class java.lang.Object

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

Constructor Detail

ComponentWrapper

public ComponentWrapper(T activeComponent)

Constructs a ComponentWrapper around the given Component.

Parameters:

activeComponent - a Component that shows and edits a property value.

Method Detail

getLogger

protected java.util.logging.Logger getLogger()

Get the Logger to log messages to for this wrapper. By default will return a Logger based on the fully qualified class name that has been initialised by the DBLog framework.

initialise

public final void initialise(ComponentContext ctxt)

Called once on create of each ComponentWrapper to initialise the DBObjectProvider, DBObject etc. Subclasses can override initialiseComponent() to customise the init behaviour.

An initialised wrapper is not active. You must call setActive(boolean) to activate the wrapper and set the initial property value from the underlying DBObject.

Parameters:

ctxt - the context containing all the information a wrapper should need to initialise.

refreshObject

public boolean refreshObject(DBObject refreshedObject)

Refreshes this ComponentWrapper with a new updatedObject for its ComponentContext. If the current updatedObject is already refreshedObject then false is returned.

Parameters:

refreshedObject - the new updatedObject to refresh the wrapper with

Returns:

true if the updatedObject was changed.

setActive

public final void setActive(boolean active)

Sets whether this ComponentWrapper is active - i.e. whether it should be listening for DBObject updates and reflecting them in the UI, and also whether UI events should update the DBObject model.

Parameters:

active - whether to active the listeners

isActive

public final boolean isActive()

Tests whether this ComponentWrapper is active (i.e. it is listening for changes to the UI and reflecting them in the DBObject, and vice-versa).

Returns:

true if the listeners are active

setActiveImpl

protected void setActiveImpl(boolean active)

Called when a ComponentWrapper is activated/deactivated - typically onEntry/onExit of the owning panel. Subclasses should use this method to add/remove object/provider listeners etc.

Parameters:

active -

isVolatile

public final boolean isVolatile()

Tests whether this ComponentWrapper wrappers a property that is volatile i.e. can become supported/unsupported as a consequence of a change to another property.

getActiveComponent

public final T getActiveComponent()

Gets the "active" Component from this wrapper. That is the component that shows the property value and is listened to for changes.

Returns:

the active component for this wrapper.

See Also:

getComponent()

createComponentForLayout

protected java.awt.Component createComponentForLayout()

Creates the Component that will be added to any layout for the given active component. By default this simply returns the active component. This is called once when the first call to getComponent() is made.

Returns:

the Component to be added to any layout.

getComponent

public final java.awt.Component getComponent()

Gets the "layout" Component from this wrapper. That is the component that should be added to any layout. If this is not the same as getActiveComponent() then it should contain the active component (e.g. in a scroll pane, or resizable component).

Returns:

the component to add to any layout for this wrapper.

See Also:

getActiveComponent()

getDefaultFocusComponent

public java.awt.Component getDefaultFocusComponent()

Gets the particular Component that is the focus of the property value. This is used when requesting focus for the property, and also used by the validation layer to know which Component should be highlighted as invalid.

By default this returns the active component.

Returns:

the focusable component that represents the actual property value.

setValidationStatus

public void setValidationStatus(java.util.Collection<ValidationException> ves,
                                oracle.ideimpl.db.validate.DBValidationHandler handler)

Sets the validation status of the wrapped property value. If appropriate this should highlight the component(s) containing the invalid value(s) to indicate where the problem is to the user.

By default this applys the status highlight to the default validation component.

Parameters:

ves - what is wrong with the value (can be null or empty to signify that the value is valid).

handler - the calling handler.

See Also:

getDefaultValidationComponent()

getDefaultValidationComponent

protected java.awt.Component getDefaultValidationComponent()

By default setValidationStatus(java.util.Collection<oracle.javatools.db.validators.ValidationException>, oracle.ideimpl.db.validate.DBValidationHandler) will apply a status indication to the component returned by this component. To customise the status highlighting beyond a single, simple component override setValidationStatus(java.util.Collection<oracle.javatools.db.validators.ValidationException>, oracle.ideimpl.db.validate.DBValidationHandler) directly.

By default this returns the default focus component.

Returns:

the default component to apply status to.

getPropertyValue

public abstract java.lang.Object getPropertyValue()

Gets the value of the property as currently set in the UI Component e.g. for a String property in a text field this returns the text currently set in the JTextField.

setPropertyValue

public abstract void setPropertyValue(java.lang.Object val)

Sets the value of the property displayed in the UI. e.g. for a String property in a text field this sets the text in the JTextField.

This does not update the DBObject model, and should only need to be called outside of this class if the DBObject model has been manually updated.

See Also:

resetPropertyValue(Object)

resetPropertyValue

public final void resetPropertyValue(java.lang.Object newValue)

Convenience method to set the given value for the property we are wrapping on both the underlying DBObject, and in the underlying Component.

Parameters:

newValue - the new property value

See Also:

setPropertyValue(Object)

setEnabled

public void setEnabled(boolean enabled)

Sets the enabled state of the components within the wrapper.

setVisible

public void setVisible(boolean visible)

Sets the visible state of the components within the wrapper.

getPropertyName

public final java.lang.String getPropertyName()

Gets the name of the property that this wrapper is editing. This is a utility method that gets the property name from the underlying ComponentContext.

getLabel

public javax.swing.JLabel getLabel()

If the Component has a JLabel associated with it this returns the label. Some components don't have labels (e.g. JCheckBox) and therefore this can return null.

getPropertyDisplayName

public java.lang.String getPropertyDisplayName()

Gets the displayable (translated) name for the property that this wrapper is editing.

See Also:

getPropertyName()

setPropertyDisplayName

public void setPropertyDisplayName(java.lang.String displayName)

Sets the displayable (translated) name for the property that this wrapper is editing. By default calling this is not required, the wrapper will use the PropertyDisplayRegistry to determine an appropriate display name for most properties.

See Also:

getPropertyDisplayName()

initialiseComponentListener

protected abstract void initialiseComponentListener()

Initialises a listener against the underlying Component that will call fireChangeEvent whenever the value in the UI is changed by the user.

NB: Only listeners on the underlying component should be registered with implementations of this method as the there is no point at which these listeners are explicitly removed.

If you wish to register a listener against some other object, it should be added and removed in an override of setActiveImpl(boolean).

This is called after initialiseComponent().

initialiseComponent

protected void initialiseComponent()

If any setup of the Component is needed after the provider/object are known override this method and implement there.

addListener

public final void addListener(java.beans.PropertyChangeListener listener)

Registers the given PropertyChangeListener with this Component to be notifed when the value in the UI is changed.

Parameters:

listener - the listener to add

addVetoListener

public final void addVetoListener(java.beans.VetoableChangeListener listener)

Registers the given VetoableChangeListener with this Component to be notifed when the value in the UI is changed. As well as the notification the listener can veto the change and it will be rolled back.

If a change is vetoed, the PropertyVetoException thrown can optionally contain a message. If the exception contains a message it will cause an error dialog to show displaying the reason (so should be translated).

Parameters:

listener - the listener to add

removeListener

public final void removeListener(java.beans.PropertyChangeListener listener)

Removes a listener previously registered with addListener(java.beans.PropertyChangeListener)

Parameters:

listener - the listener to remove

removeVetoListener

public final void removeVetoListener(java.beans.VetoableChangeListener listener)

Removes a listener previously registered with addVetoListener(java.beans.VetoableChangeListener)

Parameters:

listener - the listener to remove

processComponent

public void processComponent(boolean editable,
                             boolean allowRecreate)

Processes the underlying component by checking whether the property is supported and hiding or disabling the wrapped component accordingly. This uses the PropertyManager for the underlying DBObjectProvider to determine whether the property is supported at all (if not the Component will be hidden), or just cannot be updated (so we disable the Component instead).

Parameters:

editable - whether the object is editable at all

allowRecreate - whether to enable components for properties that will require a drop/create in order to change them.

checkPropertyIsSupported

protected boolean checkPropertyIsSupported()

Called to determine whether the wrapper property is supported for the object in the current ComponentContext.

getExistingPropertyValue

protected final java.lang.Object getExistingPropertyValue()

Gets the existing property value from the underlying DBObject model (the updated object). This can be different to the current value in the UI.

Returns:

the property value current set on the DBObject.

See Also:

getUpdatedObject(), getPropertyValue()

getOriginalPropertyValue

protected final java.lang.Object getOriginalPropertyValue()

Gets the original property value from the underlying DBObject model (i.e. the property value from the original object).

Returns:

the property value current set on the original DBObject, or null if there is no original object.

See Also:

getOriginalObject()

fireChangeEvent

protected final boolean fireChangeEvent()

This method should be called when the UI has been changed and the value from the UI should be committed to the underlying DBObject model. This will commit the property and fire an appropriate event to any registered PropertyChangeListeners.

If a VetoableChangeListener is registered, and vetoes the change, the user will be presented with an error dialog if the exception contains a message. The UI will then be reverted back and this method will return false. To avoid a revert call fireVetoableChangeEvent() and deal with the veto appropriately.

Returns:

true if a change to the property was successfully committed and events fired.

See Also:

fireVetoableChangeEvent()

fireVetoableChangeEvent

protected final void fireVetoableChangeEvent()
                                      throws java.beans.PropertyVetoException

This method should be called when the UI has been changed and the value from the UI should be committed to the underlying DBObject model, but the commit is vetoable. This will commit the property and fire an appropriate event to any registered PropertyChangeListeners.

If a VetoableChangeListener is registered, and vetoes the change, the veto will be thrown by this method (and the DBObject model won't have been updated).

Throws:

java.beans.PropertyVetoException - if the current state of the UI could not be committed to the DBObject model.

See Also:

fireChangeEvent()

showError

protected void showError(java.lang.String message)

Shows an error message relating to the value of the wrapped Component to the user. The default implementation simply shows an error dialog with the given message.

Parameters:

message - the error message to show

getPropertyHelper

protected final PropertyHelper getPropertyHelper()

Gets a PropertyHelper instance that is cached for this editor.

getProvider

protected final DBObjectProvider getProvider()

Gets the DBObjectProvider that the object being edited is from/for. This is a utility method that gets the DBObjectProvider from the underlying ComponentContext.

getUpdatedObject

protected final DBObject getUpdatedObject()

Gets the object that is being edited or created. In the case of an edit this is a copy of the original object. This is a utility method that gets the updated object from the underlying ComponentContext.

getOriginalObject

protected final DBObject getOriginalObject()

Gets the original object that is being edited. If we are creating a new object this will be null. This is a utility method that gets the original object from the underlying ComponentContext.

isSupported

public final boolean isSupported()

Is this property supported for the context DB Object

getComponentContext

public final ComponentContext getComponentContext()

Gets the context that this ComponentWrapper was initialised with.

getCellEditorComponent

public java.awt.Component getCellEditorComponent()

If this ComponentWrapper is used within a JTable to provide edit capabilities for a cell this method is used to get the editor component. By default it returns getActiveComponent(), override to provide custom JTable behaviour.

setReadOnly

public final void setReadOnly(boolean readOnly)

Sets the component to be read-only, such that any attempt to change its value will be ignored and reset. Subclasses may change the visual appearence of the active component by overriding setUIReadOnly(boolean).

NB Typically clients will NOT need to call this as the ComponentWrapper framework will hide or disable components that are not supported, but is provided if there are any special cases where this default behaviour is to be overriden.

Parameters:

readOnly - whether the component should be made read only.

setUIReadOnly

protected void setUIReadOnly(boolean readOnly)

Subclasses may implement this method to make the UI readonly on request.

Parameters:

readOnly -

See Also:

setReadOnly(boolean)

resourceComponent

protected void resourceComponent(oracle.ideimpl.db.DBUIResourceHelper resHelp)

Sets up the resourcing of the component and its label (if one exists). By default the label is given the property display name and the active component named (for testability) using the property name.

This is called once when the wrapper is registered with the ComponentFactory.

Parameters:

resHelp - the resource helper to use to do the resourcing (will contain a base name from the owning panel).