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
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, 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(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. |
ValueBinding |
getValueBinding(java.lang.String name)
Deprecated.
this has been replaced by
getValueExpression(java.lang.String). |
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 |
setValueBinding(java.lang.String name,
ValueBinding binding)
Deprecated.
This has been replaced by
setValueExpression(java.lang.String, javax.el.ValueExpression). |
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, 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, 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[] 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 ValueBinding getValueBinding(java.lang.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 UIComponentBasename - Name of the attribute or property for which to retrieve
a ValueBindingnulljava.lang.NullPointerException - if name
is nullpublic void setValueBinding(java.lang.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 UIComponentBasename - Name of the attribute or property for which to set
a ValueBindingbinding - The ValueBinding to set, or null
to remove any currently set ValueBindingjava.lang.NullPointerException - if name
is nullpublic 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