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
javax.faces.render.Renderer for this component must
perform the following logic on getConvertedValue()
:
Obtain the
javax.faces.convert.Converter using the following algorithm:
If the component has an attached
javax.faces.convert.Converter, use it.
If not, look for a
ValueExpression for value
(if any). The
ValueExpression must point to something that
is:
An array of primitives (such as int[]
).
Look up the registered by-class
javax.faces.convert.Converterfor this primitive type.
An array of objects (such as Integer[]
or
String[]
). Look up the registered by-class
javax.faces.convert.Converter 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
javax.faces.convert.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
javax.faces.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.
modelType to targetForConvertedValues mapping
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.