public class UISelectMany extends UIInput
UISelectMany is a
UIComponent
that represents the user's choice of a zero or
more items from among a discrete set of available options. The user
can modify the selected values. Optionally, the component can be
preconfigured with zero or more currently selected items, by storing
them as an array or
Collection
in the value
property of
the component.
This component is generally rendered as a select box or a group of checkboxes.
By default, the rendererType
property must be set to
"javax.faces.Listbox
". This value can be changed by
calling the setRendererType()
method.
The Renderer
for this component must
perform the following logic on getConvertedValue()
:
Obtain the
Converter
using the following algorithm:If the component has an attached
Converter
, use it.If not, look for a
ValueExpression
forvalue
(if any). TheValueExpression
must point to something that is:
An array of primitives (such as
int[]
). Look up the registered by-classConverter
for this primitive type.An array of objects (such as
Integer[]
orString[]
). Look up the registered by-classConverter
for the underlying element type.A
java.util.Collection
. Do not convert the values. Instead, convert the provided set of available options to string, exactly as done during render response, and for any match with the submitted values, add the available option as object to the collection.If for any reason a
Converter
cannot be found, assume the type to be a String array.
Use the selected Converter
(if any) to
convert each element in the values array from the request to the
proper type, and store the result of
each conversion in a data structure, called
targetForConvertedValues for discussion. Create
targetForConvertedValues using the following
algorithm.
If the component has a ValueExpression
for
value
and the type of the expression is an array, let
targetForConvertedValues be a new array of the expected
type.
If the component has a ValueExpression
for
value
, let modelType be the type of the value
expression. If modelType is a Collection
, do
the following to arrive at targetForConvertedValues:
Ask the component for its attribute under the key
"collectionType
", without the quotes. If there is a
value for that key, the value must be a String that is a fully
qualified Java class name, or a Class
object, or a
ValueExpression
that evaluates to a String or a
Class
. In all cases, the value serves to identify the
concrete type of the class that implements Collection
.
For discussion, this is called collectionType. Let
targetForConvertedValues be a new instance of
Collection
implemented by the concrete class specified
in collectionType. If, collectionType can not be
discovered, or an instance of Collection
implemented by
the concrete class specified in collectionType cannot be
created, throw a FacesException
with a correctly
localized error message. Note that FacesException
is
thrown instead of ConverterException
because this case
would only arise from developer error, rather than end-user
error.
If there is no "collectionType
" attribute, call
getValue()
on the component. The result will implement
Collection
. If the result also implements
Cloneable
, let targetForConvertedValues be the
result of calling its clone()
method, then calling
clear()
on the cloned Collection
. If
unable to clone the value for any reason, log a message and proceed
to the next step.
If modelType is a concrete class, let
targetForConvertedValues be a new instance of that class.
Otherwise, the concrete type for targetForConvertedValues is
taken from the following table. All classes are in the
java.util
package. All collections must be created with
an initial capacity equal to the length of the values array from the
request.
If modelType is an instance of | then targetForConvertedValues must be an instance of |
---|---|
SortedSet |
TreeSet |
Queue |
LinkedList |
Set |
HashSet |
anything else | ArrayList |
If the component does not have a ValueExpression
for value
, let targetForConvertedValues be an
array of type Object
.
Return targetForConvertedValues after populating it with the converted values.
Modifier and Type | Field and Description |
---|---|
static String |
COMPONENT_FAMILY
The standard component family for this component.
|
static String |
COMPONENT_TYPE
The standard component type for this component.
|
static String |
INVALID_MESSAGE_ID
The message identifier of the
FacesMessage to be created if
a value not matching the available options is specified. |
ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE, CONVERSION_MESSAGE_ID, EMPTY_STRING_AS_NULL_PARAM_NAME, REQUIRED_MESSAGE_ID, UPDATE_MESSAGE_ID, VALIDATE_EMPTY_FIELDS_PARAM_NAME
ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY
Constructor and Description |
---|
UISelectMany()
Create a new
UISelectMany instance with default property
values. |
Modifier and Type | Method and Description |
---|---|
protected boolean |
compareValues(Object previous,
Object value)
Return
true if the new value is different from the
previous value. |
String |
getFamily()
Return the identifier of the component family to which this component belongs. |
Object[] |
getSelectedValues()
Return the currently selected values, or
null if there
are no currently selected values. |
ValueBinding |
getValueBinding(String name)
Deprecated.
this has been replaced by
getValueExpression(java.lang.String) . |
javax.el.ValueExpression |
getValueExpression(String name)
Return any
ValueExpression set for value if a
ValueExpression for selectedValues is requested;
otherwise, perform the default superclass processing for this method. |
void |
setSelectedValues(Object[] selectedValues)
Set the currently selected values, or
null to indicate
that there are no currently selected values. |
void |
setValueBinding(String name,
ValueBinding binding)
Deprecated.
This has been replaced by
setValueExpression(java.lang.String, javax.el.ValueExpression) . |
void |
setValueExpression(String name,
javax.el.ValueExpression binding)
Store any
ValueExpression specified for
selectedValues under value instead;
otherwise, perform the default superclass processing for this method. |
protected void |
validateValue(FacesContext context,
Object value)
In addition to the standard
validation behavior inherited from
UIInput , ensure that
any specified values are equal to one of the available options. |
addValidator, addValueChangeListener, clearInitialState, decode, getConvertedValue, getConverterMessage, getRequiredMessage, getSubmittedValue, getValidator, getValidatorMessage, getValidators, getValue, getValueChangeListener, getValueChangeListeners, isEmpty, isImmediate, isLocalValueSet, isRequired, isValid, markInitialState, processDecodes, processUpdates, processValidators, removeValidator, removeValueChangeListener, resetValue, restoreState, saveState, setConverterMessage, setImmediate, setLocalValueSet, setRequired, setRequiredMessage, setSubmittedValue, setValid, setValidator, setValidatorMessage, setValue, setValueChangeListener, updateModel, validate
getConverter, getLocalValue, setConverter
addClientBehavior, addFacesListener, broadcast, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getListenersForEventClass, getParent, getPassThroughAttributes, getRenderer, getRendererType, getRendersChildren, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, subscribeToEvent, unsubscribeFromEvent
encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, visitTree
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
getConverter, getLocalValue, setConverter
public static final String COMPONENT_TYPE
The standard component type for this component.
public static final String COMPONENT_FAMILY
The standard component family for this component.
public static final String INVALID_MESSAGE_ID
The message identifier of the
FacesMessage
to be created if
a value not matching the available options is specified.
public UISelectMany()
Create a new UISelectMany
instance with default property
values.
public String getFamily()
UIComponent
Return the identifier of the component family to which this component belongs. This
identifier, in conjunction with the value of the rendererType
property, may be used to select the appropriate Renderer
for this component
instance. Note this method should NOT return null
public Object[] getSelectedValues()
Return the currently selected values, or null
if there
are no currently selected values. This is a typesafe alias for
getValue()
.
null
.public void setSelectedValues(Object[] selectedValues)
Set the currently selected values, or null
to indicate
that there are no currently selected values. This is a typesafe
alias for setValue()
.
selectedValues
- The new selected values (if any)public ValueBinding getValueBinding(String name)
getValueExpression(java.lang.String)
.Return any ValueBinding
set for value
if
a ValueBinding
for selectedValues
is
requested; otherwise, perform the default superclass processing
for this method.
This method relies on the superclass to provide the
ValueExpression
to ValueBinding
wrapping.
getValueBinding
in class UIComponentBase
name
- Name of the attribute or property for which to retrieve
a ValueBinding
null
NullPointerException
- if name
is null
public void setValueBinding(String name, ValueBinding binding)
setValueExpression(java.lang.String, javax.el.ValueExpression)
.Store any ValueBinding
specified for
selectedValues
under value
instead;
otherwise, perform the default superclass processing for this
method.
This method relies on the superclass to wrap the argument
ValueBinding
in a ValueExpression
.
setValueBinding
in class UIComponentBase
name
- Name of the attribute or property for which to set
a ValueBinding
binding
- The ValueBinding
to set, or null
to remove any currently set ValueBinding
NullPointerException
- if name
is null
public javax.el.ValueExpression getValueExpression(String name)
Return any ValueExpression
set for value
if a
ValueExpression
for selectedValues
is requested;
otherwise, perform the default superclass processing for this method.
getValueExpression
in class UIComponent
name
- Name of the attribute or property for which to retrieve
a ValueExpression
null
.NullPointerException
- if name
is null
public void setValueExpression(String name, javax.el.ValueExpression binding)
Store any ValueExpression
specified for
selectedValues
under value
instead;
otherwise, perform the default superclass processing for this method.
setValueExpression
in class UIComponent
name
- Name of the attribute or property for which to set
a ValueExpression
binding
- The ValueExpression
to set, or null
to remove any currently set ValueExpression
NullPointerException
- if name
is null
protected boolean compareValues(Object previous, Object value)
Return true
if the new value is different from the
previous value. Value comparison must not be sensitive to element order.
compareValues
in class UIInput
previous
- old value of this componentvalue
- new value of this componenttrue
if the new value is different from the
previous value, false
otherwise.protected void validateValue(FacesContext context, Object value)
In addition to the standard
validation behavior inherited from UIInput
, ensure that
any specified values are equal to one of the available options.
Before comparing each option, coerce the option value type to the
type of this component's value following the Expression Language
coercion rules. If the specified value is not equal to any of
the options, enqueue an error message and set the
valid
property to false
.
This method must explicitly
support a value argument that is a single value or a value
argument that is a Collection
or Array of
values.
If UIInput.isRequired()
returns
true
, and the current value is equal to the value of
an inner UISelectItem
whose UISelectItem.isNoSelectionOption()
method returns
true
, enqueue an error message and set the
valid
property to false
.
validateValue
in class UIInput
context
- The FacesContext
for the current requestvalue
- The converted value to test for membership.NullPointerException
- if context
is null
Comments to: faces-dev@eclipse.org.
Copyright © 2019 Eclipse Foundation. All rights reserved.
Use is subject to license terms.