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 jakarta.faces.render.Renderer for this component must perform the following logic on getConvertedValue():

Obtain the jakarta.faces.convert.Converter using the following algorithm:

If the component has an attached jakarta.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 jakarta.faces.convert.Converter for this primitive type.

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

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	UISelectMany.ArrayIterator Exposes an Array as an Iterator.

Field Summary

Modifier and Type	Field and Description
public static final String	COMPONENT_FAMILY Hides jakarta.faces.component.UIInput.COMPONENT_FAMILY. The standard component family for this component.
public static final String	COMPONENT_TYPE Hides jakarta.faces.component.UIInput.COMPONENT_TYPE. The standard component type for this component.
public static final String	INVALID_MESSAGE_ID The message identifier of the `jakarta.faces.application.FacesMessage` to be created if a value not matching the available options is specified.
private transient Object	submittedValue Hides jakarta.faces.component.UIInput.submittedValue.

Inherited from jakarta.faces.component.UIInput:: 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 validators

Constructor Summary

Access	Constructor and Description
public	UISelectMany() Create a new `UISelectMany` instance with default property values.

Method Summary

Modifier and Type	Method and Description
protected boolean	Returns: `true` if the new value is different from the previous value, `false` otherwise. compareValues(Object old value of this component previous, Object new value of this component value) Overrides jakarta.faces.component.UIInput.compareValues. Return `true` if the new value is different from the previous value.
private static int	countElementOccurrence(Object object whose occurrance is to be counted in the array. element, Object[] object representing the old value of this component. array) Return the number of occurrences of a particular element in the array.
public String	getFamily() Overrides jakarta.faces.component.UIInput.getFamily. Return the identifier of the component family to which this component belongs.
public Object[]	Returns: the selected values, or `null`. getSelectedValues() Return the currently selected values, or `null` if there are no currently selected values.
public Object	getSubmittedValue() Overrides jakarta.faces.component.UIInput.getSubmittedValue. Implements jakarta.faces.component.EditableValueHolder.getSubmittedValue. Return the submittedValue value of this `UIInput` component.
public ValueExpression	Returns: the value expression, or `null`. getValueExpression(String Name of the attribute or property for which to retrieve a `ValueExpression` name) Overrides jakarta.faces.component.UIComponent.getValueExpression. Return any `ValueExpression` set for `value` if a `ValueExpression` for `selectedValues` is requested; otherwise, perform the default superclass processing for this method.
private Iterator<E>	getValuesIterator(Object value)
public void	setSelectedValues(Object[] The new selected values (if any) selectedValues) Set the currently selected values, or `null` to indicate that there are no currently selected values.
public void	setSubmittedValue(Object The new submitted value submittedValue) Overrides jakarta.faces.component.UIInput.setSubmittedValue. Implements jakarta.faces.component.EditableValueHolder.setSubmittedValue. Set the submittedValue value of this `UIInput` component.
public void	setValueExpression(String Name of the attribute or property for which to set a `ValueExpression` name, ValueExpression The `ValueExpression` to set, or `null` to remove any currently set `ValueExpression` binding) Overrides jakarta.faces.component.UIComponent.setValueExpression. Store any `ValueExpression` specified for `selectedValues` under `value` instead; otherwise, perform the default superclass processing for this method.
private static Object[]	Returns: an Object array, or null if the incoming value is not in fact an array at all. toObjectArray(Object object containing the primitive values primitiveArray) Convert an array of primitives to an array of boxed objects.
protected void	validateValue(FacesContext The `FacesContext` for the current request context, Object The converted value to test for membership. value) Overrides jakarta.faces.component.UIInput.validateValue. In addition to the standard validation behavior inherited from `UIInput`, ensure that any specified values are equal to one of the available options.

Field Detail

COMPONENT_FAMILY	back to summary
public static final String COMPONENT_FAMILY Hides jakarta.faces.component.UIInput.COMPONENT_FAMILY. The standard component family for this component.

COMPONENT_FAMILY

back to summary

public static final String COMPONENT_FAMILY

Hides jakarta.faces.component.UIInput.COMPONENT_FAMILY.

The standard component family for this component.

COMPONENT_TYPE	back to summary
public static final String COMPONENT_TYPE Hides jakarta.faces.component.UIInput.COMPONENT_TYPE. The standard component type for this component.

COMPONENT_TYPE

back to summary

public static final String COMPONENT_TYPE

Hides jakarta.faces.component.UIInput.COMPONENT_TYPE.

The standard component type for this component.

INVALID_MESSAGE_ID	back to summary
public static final String INVALID_MESSAGE_ID The message identifier of the `jakarta.faces.application.FacesMessage` to be created if a value not matching the available options is specified.

submittedValue	back to summary
private transient Object submittedValue Hides jakarta.faces.component.UIInput.submittedValue.

Constructor Detail

UISelectMany	back to summary
public UISelectMany() Create a new `UISelectMany` instance with default property values.

Method Detail

compareValues back to summary

compareValues	back to summary
protected boolean compareValues(Object previous, Object value) Overrides jakarta.faces.component.UIInput.compareValues. Return `true` if the new value is different from the previous value. Value comparison must not be sensitive to element order. Parameters previous:Object old value of this component value:Object new value of this component Returns:boolean `true` if the new value is different from the previous value, `false` otherwise. Annotations @Override

protected boolean compareValues(Object previous, Object value)

Overrides jakarta.faces.component.UIInput.compareValues.

Return true if the new value is different from the previous value. Value comparison must not be sensitive to element order.

Parameters

previous:Object: old value of this component
value:Object: new value of this component

Returns:boolean

true if the new value is different from the previous value, false otherwise.

Annotations

@Override

countElementOccurrence	back to summary
private static int countElementOccurrence(Object element, Object[] array) Return the number of occurrences of a particular element in the array. Parameters element:Object object whose occurrance is to be counted in the array. array:Object[] object representing the old value of this component.

countElementOccurrence

back to summary

private static int countElementOccurrence(Object element, Object[] array)

Return the number of occurrences of a particular element in the array.

Parameters

element:Object: object whose occurrance is to be counted in the array.
array:Object[]: object representing the old value of this component.

getFamily back to summary

getFamily	back to summary
public String getFamily() Overrides jakarta.faces.component.UIInput.getFamily. Doc from jakarta.faces.component.UIComponent.getFamily. 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` Returns:String the component family (not null). Annotations @Override

public String getFamily()

Overrides jakarta.faces.component.UIInput.getFamily.

Doc from jakarta.faces.component.UIComponent.getFamily.

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

Returns:String

the component family (not null).

Annotations

@Override

getSelectedValues back to summary

getSelectedValues	back to summary
public Object[] getSelectedValues() Return the currently selected values, or `null` if there are no currently selected values. This is a typesafe alias for `getValue()`. Returns:Object[] the selected values, or `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().

Returns:Object[]: the selected values, or null.

getSubmittedValue back to summary

getSubmittedValue	back to summary
public Object getSubmittedValue() Overrides jakarta.faces.component.UIInput.getSubmittedValue. Implements jakarta.faces.component.EditableValueHolder.getSubmittedValue. Doc from jakarta.faces.component.UIInput.getSubmittedValue. Return the submittedValue value of this `UIInput` component. This method should only be used by the `decode()` and `validate()` method of this component, or its corresponding `Renderer`. Returns:Object Doc from jakarta.faces.component.EditableValueHolder.getSubmittedValue. the submitted value. Annotations @Override

public Object getSubmittedValue()

Overrides jakarta.faces.component.UIInput.getSubmittedValue.

Implements jakarta.faces.component.EditableValueHolder.getSubmittedValue.

Doc from jakarta.faces.component.UIInput.getSubmittedValue.

Return the submittedValue value of this UIInput component. This method should only be used by the decode() and validate() method of this component, or its corresponding Renderer.

Returns:Object

Doc from jakarta.faces.component.EditableValueHolder.getSubmittedValue.

the submitted value.

Annotations

@Override

getValueExpression back to summary

getValueExpression	back to summary
public ValueExpression getValueExpression(String name) Overrides jakarta.faces.component.UIComponent.getValueExpression. Return any `ValueExpression` set for `value` if a `ValueExpression` for `selectedValues` is requested; otherwise, perform the default superclass processing for this method. Parameters name:String Name of the attribute or property for which to retrieve a `ValueExpression` Returns:ValueExpression the value expression, or `null`. Annotations @Override Exceptions NullPointerException: if `name` is `null` Since 1.2

public ValueExpression getValueExpression(String name)

Overrides jakarta.faces.component.UIComponent.getValueExpression.

Return any ValueExpression set for value if a ValueExpression for selectedValues is requested; otherwise, perform the default superclass processing for this method.

Parameters

name:String: Name of the attribute or property for which to retrieve a ValueExpression

Returns:ValueExpression

the value expression, or null.

Annotations

@Override

Exceptions

NullPointerException:: if name is null

Since

1.2

getValuesIterator	back to summary
private Iterator<E> getValuesIterator(Object value)

setSelectedValues back to summary

setSelectedValues	back to summary
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()`. Parameters selectedValues:Object[] The new selected values (if any)

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().

Parameters

selectedValues:Object[]: The new selected values (if any)

setSubmittedValue back to summary

setSubmittedValue	back to summary
public void setSubmittedValue(Object submittedValue) Overrides jakarta.faces.component.UIInput.setSubmittedValue. Implements jakarta.faces.component.EditableValueHolder.setSubmittedValue. Doc from jakarta.faces.component.UIInput.setSubmittedValue. Set the submittedValue value of this `UIInput` component. This method should only be used by the `decode()` and `validate()` method of this component, or its corresponding `Renderer`. Parameters submittedValue:Object The new submitted value Annotations @Override

public void setSubmittedValue(Object submittedValue)

Overrides jakarta.faces.component.UIInput.setSubmittedValue.

Implements jakarta.faces.component.EditableValueHolder.setSubmittedValue.

Doc from jakarta.faces.component.UIInput.setSubmittedValue.

Set the submittedValue value of this UIInput component. This method should only be used by the decode() and validate() method of this component, or its corresponding Renderer.

Parameters

submittedValue:Object: The new submitted value

Annotations

@Override

setValueExpression back to summary

setValueExpression	back to summary
public void setValueExpression(String name, ValueExpression binding) Overrides jakarta.faces.component.UIComponent.setValueExpression. Store any `ValueExpression` specified for `selectedValues` under `value` instead; otherwise, perform the default superclass processing for this method. Parameters name:String Name of the attribute or property for which to set a `ValueExpression` binding:ValueExpression The `ValueExpression` to set, or `null` to remove any currently set `ValueExpression` Annotations @Override Exceptions NullPointerException: if `name` is `null` Since 1.2

public void setValueExpression(String name, ValueExpression binding)

Overrides jakarta.faces.component.UIComponent.setValueExpression.

Store any ValueExpression specified for selectedValues under value instead; otherwise, perform the default superclass processing for this method.

Parameters

name:String: Name of the attribute or property for which to set a ValueExpression
binding:ValueExpression: The ValueExpression to set, or null to remove any currently set ValueExpression

Annotations

@Override

Exceptions

NullPointerException:: if name is null

Since

1.2

toObjectArray	back to summary
private static Object[] toObjectArray(Object primitiveArray) Convert an array of primitives to an array of boxed objects. Parameters primitiveArray:Object object containing the primitive values Returns:Object[] an Object array, or null if the incoming value is not in fact an array at all.

toObjectArray

back to summary

private static Object[] toObjectArray(Object primitiveArray)

Convert an array of primitives to an array of boxed objects.

Parameters

primitiveArray:Object: object containing the primitive values

Returns:Object[]

an Object array, or null if the incoming value is not in fact an array at all.

validateValue back to summary

validateValue	back to summary
protected void validateValue(FacesContext context, Object value) Overrides jakarta.faces.component.UIInput.validateValue. 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 `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`. Parameters context:FacesContext The `FacesContext` for the current request value:Object The converted value to test for membership. Annotations @Override Exceptions NullPointerException: if `context` is `null`

protected void validateValue(FacesContext context, Object value)

Overrides jakarta.faces.component.UIInput.validateValue.

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 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.

Parameters

context:FacesContext: The FacesContext for the current request
value:Object: The converted value to test for membership.

Annotations

@Override

Exceptions

NullPointerException:: if context is null

jakarta.faces.component back to summary

private final Class UISelectMany.ArrayIterator

Class Inheritance

extends Object
implements Iterator

java.lang.Object
jakarta.faces.component.UISelectMany.ArrayIterator

All Implemented Interfaces

java.util.Iterator

Exposes an Array as an Iterator.

Field Summary

Modifier and Type	Field and Description
private int	idx
private final int	length
private final Object	value

Constructor Summary

Access	Constructor and Description
pack-priv	ArrayIterator(Object value)

Method Summary

Modifier and Type	Method and Description
public boolean	hasNext() Implements java.util.Iterator.hasNext. Returns `true` if the iteration has more elements.
public Object	next() Implements java.util.Iterator.next. Returns the next element in the iteration.
public void	remove() Overrides default java.util.Iterator.remove. Removes from the underlying collection the last element returned by this iterator (optional operation).

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

idx	back to summary
private int idx

length	back to summary
private final int length

value	back to summary
private final Object value

Constructor Detail

ArrayIterator	back to summary
pack-priv ArrayIterator(Object value)

Method Detail

hasNext back to summary

hasNext	back to summary
public boolean hasNext() Implements java.util.Iterator.hasNext. Doc from java.util.Iterator.hasNext. Returns `true` if the iteration has more elements. (In other words, returns `true` if `next` would return an element rather than throwing an exception.) Returns:boolean `true` if the iteration has more elements Annotations @Override

public boolean hasNext()

Implements java.util.Iterator.hasNext.

Doc from java.util.Iterator.hasNext.

Returns true if the iteration has more elements. (In other words, returns true if next would return an element rather than throwing an exception.)

Returns:boolean

true if the iteration has more elements

Annotations

@Override

next	back to summary
public Object next() Implements java.util.Iterator.next. Doc from java.util.Iterator.next. Returns the next element in the iteration. Returns:Object the next element in the iteration Annotations @Override

back to summary

public Object next()

Implements java.util.Iterator.next.

Doc from java.util.Iterator.next.

Returns the next element in the iteration.

Returns:Object

the next element in the iteration

Annotations

@Override

remove back to summary

remove	back to summary
public void remove() Overrides default java.util.Iterator.remove. Doc from java.util.Iterator.remove. Removes from the underlying collection the last element returned by this iterator (optional operation). This method can be called only once per call to `next`. The behavior of an iterator is unspecified if the underlying collection is modified while the iteration is in progress in any way other than by calling this method, unless an overriding class has specified a concurrent modification policy. The behavior of an iterator is unspecified if this method is called after a call to the `forEachRemaining` method. Annotations @Override

public void remove()

Overrides default java.util.Iterator.remove.

Doc from java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation). This method can be called only once per call to next.

The behavior of an iterator is unspecified if the underlying collection is modified while the iteration is in progress in any way other than by calling this method, unless an overriding class has specified a concurrent modification policy.

The behavior of an iterator is unspecified if this method is called after a call to the forEachRemaining method.

Annotations

@Override

public Class UISelectMany

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class UISelectMany.ArrayIterator

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail