Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.faces.component
Class UISelectMany

    java.lang.Object
      javax.faces.component.UIComponent
          javax.faces.component.UIComponentBase
              javax.faces.component.UIOutput
                  javax.faces.component.UIInput
                      javax.faces.component.UISelectMany

All Implemented Interfaces:
  java.util.EventListener, EditableValueHolder, PartialStateHolder, StateHolder, TransientStateHolder, ValueHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder

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

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.

    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.

Field Summary
`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.

Fields inherited from class javax.faces.component.UIInput
`CONVERSION_MESSAGE_ID, REQUIRED_MESSAGE_ID, UPDATE_MESSAGE_ID, VALIDATE_EMPTY_FIELDS_PARAM_NAME`

Fields inherited from class javax.faces.component.UIComponent
`ATTRS_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 Summary
`UISelectMany()` Create a new `UISelectMany` instance with default property values.

Method Summary
`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)`.
`javax.el.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, javax.el.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.

Methods inherited from class javax.faces.component.UIInput
`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, validate`

Methods inherited from class javax.faces.component.UIOutput
`getConverter, getLocalValue, setConverter`

Methods inherited from class javax.faces.component.UIComponentBase
`addClientBehavior, addFacesListener, broadcast, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getListenersForEventClass, getParent, getRenderer, getRendererType, getRendersChildren, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, subscribeToEvent, unsubscribeFromEvent`

Methods inherited from class javax.faces.component.UIComponent
`encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, visitTree`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface javax.faces.component.ValueHolder
`getConverter, getLocalValue, setConverter`

Field Detail

### COMPONENT_TYPE

    public static final java.lang.String COMPONENT_TYPE

  The standard component type for this component.

  See Also:
    Constant Field Values

### COMPONENT_FAMILY

    public static final java.lang.String COMPONENT_FAMILY

  The standard component family for this component.

  See Also:
    Constant Field Values

### INVALID_MESSAGE_ID

    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.

  See Also:
    Constant Field Values

Constructor Detail

### UISelectMany

    public UISelectMany()

  Create a new `UISelectMany` instance with default property values.

Method Detail

### getFamily

    public java.lang.String getFamily()

  Description copied from class: `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.

  Overrides:
    `getFamily` in class `UIInput`

### getSelectedValues

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

### setSelectedValues

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

  Parameters:
    `selectedValues` - The new selected values (if any)

### getValueBinding

    public ValueBinding getValueBinding(java.lang.String name)

  Deprecated. this has been replaced by `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.

  Overrides:
    `getValueBinding` in class `UIComponentBase`
  Parameters:
    `name` - Name of the attribute or property for which to retrieve a `ValueBinding`
  Throws:
    `java.lang.NullPointerException` - if `name` is `null`

### setValueBinding

    public void setValueBinding(java.lang.String name,
                                ValueBinding binding)

  Deprecated. This has been replaced by `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`.

  Overrides:
    `setValueBinding` in class `UIComponentBase`
  Parameters:
    `name` - Name of the attribute or property for which to set a `ValueBinding`
    `binding` - The `ValueBinding` to set, or `null` to remove any currently set `ValueBinding`
  Throws:
    `java.lang.NullPointerException` - if `name` is `null`

### getValueExpression

    public javax.el.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.

  Overrides:
    `getValueExpression` in class `UIComponent`
  Parameters:
    `name` - Name of the attribute or property for which to retrieve a `ValueExpression`
  Throws:
    `java.lang.NullPointerException` - if `name` is `null`
  Since:
    1.2

### setValueExpression

    public void setValueExpression(java.lang.String name,
                                   javax.el.ValueExpression binding)

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

  Overrides:
    `setValueExpression` in class `UIComponent`
  Parameters:
    `name` - Name of the attribute or property for which to set a `ValueExpression`
    `binding` - The `ValueExpression` to set, or `null` to remove any currently set `ValueExpression`
  Throws:
    `java.lang.NullPointerException` - if `name` is `null`
  Since:
    1.2

### compareValues

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

  Overrides:
    `compareValues` in class `UIInput`
  Parameters:
    `previous` - old value of this component
    `value` - new value of this component

### validateValue

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

  Overrides:
    `validateValue` in class `UIInput`
  Parameters:
    `context` - The `FacesContext` for the current request
    `value` - The converted value to test for membership.
  Throws:
    `java.lang.NullPointerException` - if `context` is `null`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2002-2010 Oracle America Inc, Inc. All Rights Reserved.