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
Converterusing the following algorithm:If the component has an attached
Converter, use it.If not, look for a
ValueExpressionforvalue(if any). TheValueExpressionmust point to something that is:
An array of primitives (such as
int[]). Look up the registered by-classConverterfor this primitive type.An array of objects (such as
Integer[]orString[]). Look up the registered by-classConverterfor 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
Convertercannot 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 java.lang.String |
COMPONENT_FAMILY
The standard component family for this component.
|
static java.lang.String |
COMPONENT_TYPE
The standard component type for this component.
|
static java.lang.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_NAMEATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, FACETS_KEY, 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(java.lang.Object previous,
java.lang.Object value)
Return
true if the new value is different from the previous value. |
java.lang.String |
getFamily()
Return the identifier of the component family to which this component belongs. |
java.lang.Object[] |
getSelectedValues()
Return the currently selected values, or
null if there are no currently selected values. |
java.lang.Object |
getSubmittedValue()
Return the submittedValue value of this
UIInput component. |
ValueExpression |
getValueExpression(java.lang.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(java.lang.Object[] selectedValues)
Set the currently selected values, or
null to indicate that there are no currently selected values. |
void |
setSubmittedValue(java.lang.Object submittedValue)
Set the submittedValue value of this
UIInput component. |
void |
setValueExpression(java.lang.String name,
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,
java.lang.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, getValidatorMessage, getValidators, getValue, getValueChangeListeners, isEmpty, isImmediate, isLocalValueSet, isRequired, isValid, markInitialState, processDecodes, processUpdates, processValidators, removeValidator, removeValueChangeListener, resetValue, restoreState, saveState, setConverterMessage, setImmediate, setLocalValueSet, setRequired, setRequiredMessage, setValid, setValidatorMessage, setValue, updateModel, validategetConverter, getLocalValue, setConverteraddClientBehavior, 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, unsubscribeFromEventencodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, visitTreeclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitgetConverter, getLocalValue, setConverterpublic static final java.lang.String COMPONENT_TYPE
The standard component type for this component.
public static final java.lang.String COMPONENT_FAMILY
The standard component family for this component.
public static final java.lang.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 java.lang.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 java.lang.Object getSubmittedValue()
UIInput
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.
getSubmittedValue in interface EditableValueHoldergetSubmittedValue in class UIInputpublic void setSubmittedValue(java.lang.Object submittedValue)
UIInput
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.
setSubmittedValue in interface EditableValueHoldersetSubmittedValue in class UIInputsubmittedValue - The new submitted valuepublic java.lang.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(java.lang.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 ValueExpression getValueExpression(java.lang.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 UIComponentname - Name of the attribute or property for which to retrieve a ValueExpressionnull.java.lang.NullPointerException - if name is nullpublic void setValueExpression(java.lang.String name,
ValueExpression binding)
Store any ValueExpression specified for selectedValues under value instead;
otherwise, perform the default superclass processing for this method.
setValueExpression in class UIComponentname - Name of the attribute or property for which to set a ValueExpressionbinding - The ValueExpression to set, or null to remove any currently set
ValueExpressionjava.lang.NullPointerException - if name is nullprotected boolean compareValues(java.lang.Object previous,
java.lang.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 UIInputprevious - 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, java.lang.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 UIInputcontext - The FacesContext for the current requestvalue - The converted value to test for membership.java.lang.NullPointerException - if context is null