Module jakarta.faces
Package jakarta.faces.component

Class UISelectMany

java.lang.Object
jakarta.faces.component.UIComponent
jakarta.faces.component.UIComponentBase
jakarta.faces.component.UIOutput
jakarta.faces.component.UIInput
jakarta.faces.component.UISelectMany
All Implemented Interfaces:
EditableValueHolder, PartialStateHolder, StateHolder, TransientStateHolder, ValueHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener
Direct Known Subclasses:
HtmlSelectManyCheckbox, HtmlSelectManyListbox, HtmlSelectManyMenu
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 "jakarta.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 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 Converter for this primitive type.

  • An array of objects (such as Integer[] or String[]). Look up the registered by-class 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 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.

      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.