org.apache.myfaces.orchestra.dynaForm.metadata
Interface MetaField

All Known Subinterfaces:

MetaFieldWritable

public interface MetaField

Read-only representation of meta-data about a single property of an entity.

This is similar to java.beans.PropertyDescriptor, but customised for the needs of the DynaForm component.

An instance of this type is generally configured via one or more implementations of the Extractor interface. For example an Extractor could introspect java beans, or introspect a database report definition, or scan the current page template for configuration for the named field. Any settings found are then used to create MetaField definitions for fields, or when multiple Extractors are configured then later ones can override settings from earlier extractors.

Note that it is very important that all Extractor implementations properly set the canRead/canWrite properties on MetaFields. These values default to null (ie false), so if they are not correctly set then UI components can behave oddly (eg be readonly when not expected).

Method Summary

Selection[]	getAllowedSelections()
boolean	getAllowMultipleSelections()
Object	getAttribute(String name)
String	getBaseName() Returns the part of the "name" property following the last dot.
boolean	getCanRead() Indicates whether the model object has a getter method for this property.
boolean	getCanWrite() Indicates whether the model object has a setter method for this property.
Object	getComponentHandler() Get the custom "renderer" (if any) for this field.
String	getConverterBean()
Class<? extends javax.faces.convert.Converter>	getConverterClass()
String	getConverterId()
String	getDataComparator()
String	getDataSource()
String	getDataSourceDescription()
boolean	getDisabled() Specify whether this field should be regarded as "disabled for user input".
boolean	getDisplayOnly() Indicates whether the user should be allowed to edit this field.
Integer	getDisplaySize() Specifies how much space should the input/output component take up on the screen.
Integer	getMaxSize() For text fields, this limits the number of characters that can be entered.
Double	getMaxValue() For numeric fields, this specifies the maximum value permitted for this field.
Integer	getMinSize()
Double	getMinValue() For numeric fields, this specifies the minimum value permitted for this field.
String	getName() The "name" of this field.
RelationType	getRelationType() Indicates whether this property is a relation to some other object.
boolean	getRequired() Returns true if this field must have a value defined before the object is "valid".
SelectionSourceEnum	getSelectionSource()
javax.persistence.TemporalType	getTemporalType()
Class<?>	getType() The type of the property that this Field instance represents.
javax.faces.component.UIComponent	getWantedComponent()
FieldRepresentation	getWantedComponentType()
boolean	isEmbedded() In case of hierarchical structures this defines if a child class should be treatened as "embedded".
boolean	isEntityType() Returns true if the type of this field is a persistent class.
boolean	isId() Returns true when this field belongs to a persistent entity and this field is part of the entity key.

Method Detail

getName

String getName()

The "name" of this field.

The name property can contain dots, eg "foo.bar.lastname".

getBaseName

String getBaseName()

Returns the part of the "name" property following the last dot. If "name" has no dots, then this returns name.

getType

Class<?> getType()

The type of the property that this Field instance represents.

isEntityType

boolean isEntityType()

Returns true if the type of this field is a persistent class.

This should be set if the type of this field is some kind of class (ie not a primitive) and that class has the @Entity annotation on it.

isId

boolean isId()

Returns true when this field belongs to a persistent entity and this field is part of the entity key. In this situation, the field is automatically marked as "readonly" because key fields of persistent entities cannot be edited.

getDisabled

boolean getDisabled()

Specify whether this field should be regarded as "disabled for user input".

There is logically no difference between "disabled" and "display only", so it is strongly recommended that extractors set the displayOnly property and ignore this one (ie leave disabled as effectively "false"), and that UI frameworks always use displayOnly and ignore this property.

In HTML there is a difference between a "disabled" and a "readonly" input field. However as an HTML post does not include data from "disabled" fields, and the JSF 1.2 framework (at least) really screws up when expected fields are not present, "disabled" HTML inputs should not be used in JSF.

getCanRead

boolean getCanRead()

Indicates whether the model object has a getter method for this property. When no, then obviously this property cannot be displayed to the user

It is expected that one or both of getCanRead/getCanWrite is defined; if both are false then the property doesn't exist!

Normally, this would be true; write-only properties are not common. However they are technically possible. Handling these may be difficult/impossible in some presentation frameworks though; for example JSF value bindings simply don't work with write-only fields.

getCanWrite

boolean getCanWrite()

Indicates whether the model object has a setter method for this property. When no, then obviously this property is effectively read-only, as no user changes can be stored.

It is expected that one or both of getCanRead/getCanWrite is defined; if both are false then the property doesn't exist!

getDisplayOnly

boolean getDisplayOnly()

Indicates whether the user should be allowed to edit this field. This is equivalent to "getReadOnly".

Note that when getCanWrite is false, then this should be true. However even when there is a property setter (getCanWrite is true), a property may be configured as display-only for the user.

getRequired

boolean getRequired()

Returns true if this field must have a value defined before the object is "valid".

getAllowedSelections

Selection[] getAllowedSelections()

getRelationType

RelationType getRelationType()

Indicates whether this property is a relation to some other object.

For primitive fields, this returns NONE.

Obviously, fields that are relations need special handling in the user interface; it is generally not a good idea to just display their raw value and allow the user to enter any other raw value they like.

isEmbedded

boolean isEmbedded()

In case of hierarchical structures this defines if a child class should be treatened as "embedded".

• Embedded: like a composite key in hibernate
• Not Embedded: like a relation to another entity (ManyToOne)

This is not a metadata for the field itself, but for the context in which this field (or its entity) will be used

getMaxSize

Integer getMaxSize()

For text fields, this limits the number of characters that can be entered.

Question: does this limit #chars for numeric and date fields too?

getMaxValue

Double getMaxValue()

For numeric fields, this specifies the maximum value permitted for this field. Returns null for non-numeric fields.

getMinSize

Integer getMinSize()

getDisplaySize

Integer getDisplaySize()

Specifies how much space should the input/output component take up on the screen. If this is less than maxSize then the field will usually allow scrolling internally.

getMinValue

Double getMinValue()

For numeric fields, this specifies the minimum value permitted for this field. Returns null for non-numeric fields.

getWantedComponent

javax.faces.component.UIComponent getWantedComponent()

getWantedComponentType

FieldRepresentation getWantedComponentType()

getTemporalType

javax.persistence.TemporalType getTemporalType()

getAllowMultipleSelections

boolean getAllowMultipleSelections()

getSelectionSource

SelectionSourceEnum getSelectionSource()

getDataSource

String getDataSource()

getDataSourceDescription

String getDataSourceDescription()

getDataComparator

String getDataComparator()

getConverterId

String getConverterId()

getConverterClass

Class<? extends javax.faces.convert.Converter> getConverterClass()

getConverterBean

String getConverterBean()

getComponentHandler

Object getComponentHandler()

Get the custom "renderer" (if any) for this field.

This method may return:

• Null when there is no special component-handler.
• A String which is the name of a managed-bean that implements an appropriate renderer class
• An instance of an appropriate renderer class
• A ValueBinding object whose getValue method returns an instance of an appropriate renderer class

When a MetaField is populated by introspecting a java bean, this value could be set by an annotations on a bean properties. It could also be set via configuration components in the current page template, or

The "appropriate renderer class" depends upon the "gui builder" implementation being used. When the presentation layer is JSF (ie the "gui builder" is "dynaform.jsf.GuiBuilder") then the "appropriate renderer class" must be a subclass of the "dynaform.jsf.DynaFormComponentHandler" class.

getAttribute

Object getAttribute(String name)