xdev.ui

Interface Formular

All Known Implementing Classes:

XdevFormular, XdevVirtualFormular

public interface Formular

The Formular is a form container for FormularComponents and ManyToManyComponents.

The Formular can be used to display a row of a VirtualTable. Therefore the Formular must contain FormularComponents that are mapped to the columns of the VirtualTable you want to display. This can be done by the XDEV IDE or manually.

The Formular also manages n:m-relations. Therefore ManyToManyComponents can be added into this container.

The Formular provides methods to:

• display VirtualTable.VirtualTableRows like setModel(xdev.vt.VirtualTable.VirtualTableRow)
• insert VirtualTable.VirtualTableRows like insert(boolean)
• update (before loaded) VirtualTable.VirtualTableRows like update(boolean)
• delete (before loaded) VirtualTable.VirtualTableRows like delete(boolean)

Since:

4.0

Author:

XDEV Software

See Also:

XdevFormular, XdevVirtualFormular, FormularListener, FormularComponent, MasterDetailComponent, ManyToManyComponent

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Formular.WorkingState Current working state of a Formular.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CLIENT_PROPERTY_KEY Key used to store form references in client properties
static String	SAVE_STATE_AFTER_MODEL_UPDATE_PROPERTY Identifies a change in the saveStateAfterModelUpdate property.

Method Summary

Modifier and Type	Method and Description
void	addFormularListener(FormularListener l) Registers a FormularListener so that it will receive form events.
Condition	createCondition(String connector) Alias for createCondition(connector,null).
Condition	createCondition(String connector, Collection paramCollection) Creates a Condition depending on the input component's values and their conditional settings.
Condition	createCondition(String connector, Query query) Creates a Condition depending on the input component's values and their conditional settings.
QueryInfo	createQuery(String connector) Creates a query (SELECT * FROM ..) of the connected VirtualTable with a WHERE condition created by the values of the FormularComponents of this formular.
void	delete() Alias for delete(true).
void	delete(boolean synchronizeDB) Deletes the VirtualTable.VirtualTableRow represented by this Formular from the set VirtualTable.
Iterable<FormularComponent>	formComponents()
Object	getClientProperty(Object key) Returns the value of the property with the specified key.
Map<String,Object>	getData(boolean withNulls) Returns a Map containing all values of this Formular / the mapped components in the Formular.
FormularListener[]	getFormularListeners()
Object	getHiddenField(String name) Returns the value of the hidden field with the specified name.
Iterable<String>	getHiddenFieldNames() Returns all hidden field names of this form.
boolean	getSaveStateAfterModelUpdate() Determines if the formular saves its state after an update of the model.
String	getURLAdd() Returns a parameter list consisting of key value pairs containing all components of this Formular and their values.
VirtualTable	getVirtualTable() Returns the assigned VirtualTable of this Formular.
VirtualTable.VirtualTableRow	getVirtualTableRow() Returns the current assigned VirtualTable.VirtualTableRow.
Formular.WorkingState	getWorkingState() Returns the working state of the form.
boolean	hasStateChanged() Checks if one of the FormularComponent's or ManyToManyComponent's state since the last call of saveState() has changed.
void	insert() Alias for insert(true).
void	insert(boolean synchronizeDB) Propagates the values of this Formular / the mapped components in the Formular to the set VirtualTable as new row.
void	insertRowInVT(VirtualTable vt, boolean synchronizeDB) Propagates the values of this Formular / the mapped components in the Formular to the set VirtualTable as new row.
Iterable<ManyToManyComponent>	manyToManyComponents()
void	putClientProperty(Object key, Object value) Adds an arbitrary key/value "client property" to this component.
void	putHiddenField(String name, Object value) Adds an arbitrary name/value "hidden field" to this form.
void	removeFormularListener(FormularListener l) Removes the listener from the listener list of this form.
void	reset() Resets this Formular / the mapped components in the Formular to the default values of the components.
void	reset(VirtualTable vt) Resets this Formular / the mapped components in the Formular to the default values of the specified VirtualTable vt.
void	restoreState() Resets this Formular / the mapped components in the Formular to the default values of the components.
void	save() Alias for save(true).
void	save(boolean synchronizeDB) Propagates the values of this Formular / the mapped components in the Formular to the set VirtualTable as new row if the row is new to the VirtualTable, otherwise an update is performed.
void	saveState() Saves the state of all FormularComponents in this formular.
void	search(String connector, VirtualTableOwner target) Updates the model of the VirtualTableOwner target.
void	setModel(int row, VirtualTable vt) Fills this Formular / the mapped components in the Formular with the values provided by the specified row in the VirtualTable vt.
void	setModel(VirtualTable.VirtualTableRow virtualTableRow) Fills this Formular / the mapped components in the Formular with the values provided by the specified row.
void	setModel(VirtualTable vt) Resets this Formular / the mapped components in the Formular to the default values of the specified VirtualTable vt.
void	setSaveStateAfterModelUpdate(boolean saveStateAfterModelUpdate) Sets if the formular should save its state after an update of the model.
void	submit(String url, String target) Submits the contents of this Formular to the given url.
void	update() Alias for update(true).
void	update(boolean synchronizeDB) Propagates the values of this Formular / the mapped components in the Formular to the set VirtualTable / the set VirtualTable.VirtualTableRow.
void	updateRowsInVT(VirtualTable vt, KeyValues keyValues, boolean synchronizeDB) Propagates the values of this Formular / the mapped components in the Formular to the specified VirtualTable vt, to the rows which matches the given KeyValues pkv.
Validation	validateFormularComponents() Validates all FormularComponents of this formular.
Validation	validateFormularComponents(Validation validation) Validates all FormularComponents of this formular depending on an given validation object.
boolean	verifyFormularComponents() Returns ture if all values of all FormularComponents of this Formular could be verified, false otherwise.

Field Detail

CLIENT_PROPERTY_KEY

static final String CLIENT_PROPERTY_KEY

Key used to store form references in client properties

See Also:

Constant Field Values

SAVE_STATE_AFTER_MODEL_UPDATE_PROPERTY

static final String SAVE_STATE_AFTER_MODEL_UPDATE_PROPERTY

Identifies a change in the saveStateAfterModelUpdate property.

See Also:

Constant Field Values

Method Detail

getWorkingState

Formular.WorkingState getWorkingState()

Returns the working state of the form.

Returns:

the formular's current state

formComponents

Iterable<FormularComponent> formComponents()

Returns:

all form components of this form

manyToManyComponents

Iterable<ManyToManyComponent> manyToManyComponents()

Returns:

all many to many components of this form

addFormularListener

void addFormularListener(FormularListener l)

Registers a FormularListener so that it will receive form events.

Parameters:

l - the listener to register

removeFormularListener

void removeFormularListener(FormularListener l)

Removes the listener from the listener list of this form.

Parameters:

l - the listener to remove

getFormularListeners

FormularListener[] getFormularListeners()

Returns:

all registered form listeners of this form

setSaveStateAfterModelUpdate

void setSaveStateAfterModelUpdate(boolean saveStateAfterModelUpdate)

Sets if the formular should save its state after an update of the model.

Parameters:

saveStateAfterModelUpdate - true if the state should be saved, false otherwise

See Also:

setModel(VirtualTable.VirtualTableRow), saveState()

getSaveStateAfterModelUpdate

boolean getSaveStateAfterModelUpdate()

Determines if the formular saves its state after an update of the model.

Returns:

true if the state is saved, false otherwise

See Also:

setModel(VirtualTable.VirtualTableRow), saveState()

saveState

void saveState()

Saves the state of all FormularComponents in this formular.

See Also:

reset(), FormularComponent.saveState()

restoreState

void restoreState()

Resets this Formular / the mapped components in the Formular to the default values of the components.

This method is a synonym for reset()

See Also:

saveState(), FormularComponent.restoreState()

reset

void reset()

Resets this Formular / the mapped components in the Formular to the default values of the components.

This method is a synonym for restoreState()

See Also:

saveState(), FormularComponent.restoreState()

hasStateChanged

boolean hasStateChanged()

Checks if one of the FormularComponent's or ManyToManyComponent's state since the last call of saveState() has changed.

Returns:

true if one component's state has changed, false otherwise

See Also:

FormularComponent.hasStateChanged(), ManyToManyComponent.hasStateChanged()

setModel

void setModel(VirtualTable vt)

Resets this Formular / the mapped components in the Formular to the default values of the specified VirtualTable vt.

Parameters:

vt - VirtualTable to reset on.

reset

void reset(VirtualTable vt)

Resets this Formular / the mapped components in the Formular to the default values of the specified VirtualTable vt.

Alias for setModel(vt.createRow())

Parameters:

vt - VirtualTable to reset on.

setModel

void setModel(int row,
              VirtualTable vt)

Fills this Formular / the mapped components in the Formular with the values provided by the specified row in the VirtualTable vt.

Parameters:

row - the row index of the VirtualTable

vt - VirtualTable to take the data from.

See Also:

VirtualTable.VirtualTableRow, setModel(VirtualTable.VirtualTableRow)

setModel

void setModel(VirtualTable.VirtualTableRow virtualTableRow)

Fills this Formular / the mapped components in the Formular with the values provided by the specified row.

Parameters:

virtualTableRow - VirtualTable.VirtualTableRow to take the data from.

See Also:

VirtualTable.VirtualTableRow, setModel(int, VirtualTable)

putHiddenField

void putHiddenField(String name,
                    Object value)

Adds an arbitrary name/value "hidden field" to this form.

If value is null this method will remove the field.

Parameters:

name - the new hidden field name

value - the new hidden field value; if null this method will remove the field

See Also:

getHiddenField(String), getHiddenFieldNames()

getHiddenField

Object getHiddenField(String name)

Returns the value of the hidden field with the specified name. Only fields added with putHiddenField will return a non- null value.

Parameters:

name - the being queried

Returns:

the value of this hidden field or null

See Also:

putHiddenField(String, Object), getHiddenFieldNames()

getHiddenFieldNames

Iterable<String> getHiddenFieldNames()

Returns all hidden field names of this form.

Returns:

all hidden field names of this form

See Also:

putHiddenField(String, Object), getHiddenField(String)

getData

Map<String,Object> getData(boolean withNulls)

Returns a Map containing all values of this Formular / the mapped components in the Formular. The key of the Map is the component name; the value is the value of that component.

Parameters:

withNulls - true if null values should be returned; otherwise false

Returns:

a Map containing all values of this Formular / the mapped components in the Formular.

getVirtualTableRow

VirtualTable.VirtualTableRow getVirtualTableRow()

Returns the current assigned VirtualTable.VirtualTableRow.

Returns:

The current assigned VirtualTable.VirtualTableRow

See Also:

setModel(VirtualTable.VirtualTableRow)

getVirtualTable

VirtualTable getVirtualTable()

Returns the assigned VirtualTable of this Formular.

Returns:

The current assigned VirtualTable

save

void save()
   throws VirtualTableException,
          DBException

Alias for save(true).

Throws:

VirtualTableException - if the new row can't be set to the VirtualTable.

DBException - if the new row can't be propagated to the underling database.

See Also:

save(boolean)

save

void save(boolean synchronizeDB)
   throws VirtualTableException,
          DBException

Propagates the values of this Formular / the mapped components in the Formular to the set VirtualTable as new row if the row is new to the VirtualTable, otherwise an update is performed.

Parameters:

synchronizeDB - true if the new row should be propagated to the underling database as well; otherwise false.

Throws:

VirtualTableException - if the new row can't be set to the VirtualTable.

DBException - if the new row can't be propagated to the underling database.

update

void update()
     throws VirtualTableException,
            DBException

Alias for update(true).

Throws:

VirtualTableException - if the values can't be set to the VirtualTable.

DBException - if the values can't be propagated to the underling database.

See Also:

update(boolean)

update

void update(boolean synchronizeDB)
     throws VirtualTableException,
            DBException

Propagates the values of this Formular / the mapped components in the Formular to the set VirtualTable / the set VirtualTable.VirtualTableRow.

Warning: In order to be able to update a row, you need to set a VirtualTable.VirtualTableRow for this Formular. You can do this by calling setModel(int, VirtualTable) or setModel(VirtualTable.VirtualTableRow).

Parameters:

synchronizeDB - true if the changes should be propagated to the underling database as well; otherwise false.

Throws:

VirtualTableException - if the values can't be set to the VirtualTable.

DBException - if the values can't be propagated to the underling database.

See Also:

setModel(VirtualTable.VirtualTableRow)

updateRowsInVT

void updateRowsInVT(VirtualTable vt,
                    KeyValues keyValues,
                    boolean synchronizeDB)
             throws VirtualTableException,
                    DBException

Propagates the values of this Formular / the mapped components in the Formular to the specified VirtualTable vt, to the rows which matches the given KeyValues pkv.

Parameters:

vt - VirtualTable to propagate the changes to

keyValues - The values which identify the rows to update

synchronizeDB - true if the changes should be propagated to the underling database as well; otherwise false.

Throws:

VirtualTableException - if the values can't be set to the VirtualTable.

DBException - if the values can't be propagated to the underling database.

insertRowInVT

void insertRowInVT(VirtualTable vt,
                   boolean synchronizeDB)
            throws VirtualTableException,
                   DBException

Propagates the values of this Formular / the mapped components in the Formular to the set VirtualTable as new row.

Parameters:

vt - VirtualTable to propagate the new row to

synchronizeDB - true if the changes should be propagated to the underling database as well; otherwise false.

Throws:

VirtualTableException - if the values can't be set to the VirtualTable.

DBException - if the values can't be propagated to the underling database.

insert

void insert()
     throws VirtualTableException,
            DBException

Alias for insert(true).

Throws:

VirtualTableException - if the new row can't be set to VirtualTable.

DBException - if the new row can't be propagated to underling database.

See Also:

insert(boolean)

insert

void insert(boolean synchronizeDB)
     throws VirtualTableException,
            DBException

Propagates the values of this Formular / the mapped components in the Formular to the set VirtualTable as new row.

Parameters:

synchronizeDB - true if the new row should be propagated to the underling database as well; otherwise false.

Throws:

VirtualTableException - if the new row can't be set to VirtualTable.

DBException - if the new row can't be propagated to underling database.

delete

void delete()
     throws VirtualTableException,
            DBException

Alias for delete(true).

Throws:

VirtualTableException - if row can't be deleted from VirtualTable.

DBException - if the row can't be deleted from the underling database.

See Also:

delete(boolean)

delete

void delete(boolean synchronizeDB)
     throws VirtualTableException,
            DBException

Deletes the VirtualTable.VirtualTableRow represented by this Formular from the set VirtualTable.

Warning: In order to be able to delete a row, you need to set a VirtualTable.VirtualTableRow for this Formular. You can do this by calling setModel(VirtualTable.VirtualTableRow) or setModel(int, VirtualTable).

Parameters:

synchronizeDB - true if the row should also be deleted from the underling database as well; otherwise false.

Throws:

VirtualTableException - if row can't be deleted from VirtualTable.

DBException - if the row can't be deleted from the underling database.

verifyFormularComponents

boolean verifyFormularComponents()

Returns ture if all values of all FormularComponents of this Formular could be verified, false otherwise.

This method shows a message box, if a validation fails.

This is a alternative method for validateFormularComponents(), but this method returns a boolean depending on the validation's result, not the result itself.

Returns:

true if all values of all FormularComponents of this Formular could be verified, false otherwise.

validateFormularComponents

Validation validateFormularComponents()

Validates all FormularComponents of this formular.

Example:

 if(formular.validateFormularComponents().hasError())
 {
        // show message
 }
 else
 {
        formular.save();
 }
 

Returns:

the validation object containing all occured exceptions

See Also:

Validation.hasError()

validateFormularComponents

Validation validateFormularComponents(Validation validation)

Validates all FormularComponents of this formular depending on an given validation object.

Parameters:

validation -

Returns:

the given validation object

See Also:

Validation.hasError()

submit

void submit(String url,
            String target)
     throws IOException

Submits the contents of this Formular to the given url.

Parameters:

url - url to send the contents to

target - HTML target (_blank, _parent etc.)

Throws:

IOException - if the submit fails

getURLAdd

String getURLAdd()

Returns a parameter list consisting of key value pairs containing all components of this Formular and their values. e.g. ?txtFirstname=John&txtLastname=Doe

Returns:

a parameter list consisting of key value pairs containing all components of this Formular and their values.

createQuery

QueryInfo createQuery(String connector)
               throws IllegalStateException,
                      IllegalArgumentException

Creates a query (SELECT * FROM ..) of the connected VirtualTable with a WHERE condition created by the values of the FormularComponents of this formular.

Parameters:

connector - "AND" or "OR"

Returns:

The default query info of the connected VirtualTable with a WHERE condition created by the values of the FormularComponents of this formular.

Throws:

IllegalStateException - if no data binding is available

IllegalArgumentException - if connector != "AND" resp. "OR"

See Also:

createCondition(String, Collection), search(String, VirtualTableOwner)

createCondition

Condition createCondition(String connector)
                   throws IllegalArgumentException

Alias for createCondition(connector,null).

Parameters:

connector - "AND" or "OR"

Returns:

The WHERE condition depending on the input component's values, or null if no values are available

Throws:

IllegalArgumentException - if connector != "AND" resp. "OR"

See Also:

createCondition(String, Query), createCondition(String, Collection), createQuery(String)

createCondition

Condition createCondition(String connector,
                          Query query)
                   throws IllegalArgumentException

Creates a Condition depending on the input component's values and their conditional settings.

Parameters:

connector - "AND" or "OR"

query - The Query to create this WHERE condition for (optional)

Returns:

The WHERE condition depending on the input component's values, or null if no values are available

Throws:

IllegalArgumentException - if connector != "AND" resp. "OR"

See Also:

createCondition(String, Collection), createQuery(String)

createCondition

Condition createCondition(String connector,
                          Collection paramCollection)
                   throws IllegalArgumentException

Creates a Condition depending on the input component's values and their conditional settings.

Parameters:

connector - "AND" or "OR"

paramCollection - The Collection to add the WHERE condition's parameter to (optional)

Returns:

The WHERE condition depending on the input component's values, or null if no values are available

Throws:

IllegalArgumentException - if connector != "AND" resp. "OR"

See Also:

createCondition(String, Query), createQuery(String)

search

void search(String connector,
            VirtualTableOwner target)
     throws IllegalArgumentException

Updates the model of the VirtualTableOwner target.

First a Condition depending on the input component's values and their conditional settings is created and then handed over to VirtualTableOwner.updateModel(Condition, Object...) of target.

Parameters:

connector - "AND" or "OR"

target - the component to update

Throws:

IllegalArgumentException - if connector != "AND" resp. "OR"

See Also:

createCondition(String), createCondition(String, Collection), createCondition(String, Query), createQuery(String)

putClientProperty

void putClientProperty(Object key,
                       Object value)

Adds an arbitrary key/value "client property" to this component.

The get/putClientProperty methods provide access to a small per-instance hashtable. Callers can use get/putClientProperty to annotate components that were created by another module. For example, a layout manager might store per child constraints this way. For example:

 componentA.putClientProperty("to the left of",componentB);
 

If value is null this method will remove the property. Changes to client properties are reported with PropertyChange events. The name of the property (for the sake of PropertyChange events) is key.toString().

The clientProperty dictionary is not intended to support large scale extensions to form nor should be it considered an alternative to subclassing when designing a new component.

Parameters:

key - the new client property key

value - the new client property value; if null this method will remove the property

See Also:

getClientProperty(java.lang.Object)

getClientProperty

Object getClientProperty(Object key)

Returns the value of the property with the specified key. Only properties added with putClientProperty will return a non- null value.

Parameters:

key - the being queried

Returns:

the value of this property or null

See Also:

putClientProperty(java.lang.Object, java.lang.Object)