javax.faces.component
Class _ComponentAttributesMap

java.lang.Object
  extended by javax.faces.component._ComponentAttributesMap
All Implemented Interfaces:
java.io.Serializable, java.util.Map

 class _ComponentAttributesMap
extends java.lang.Object
implements java.util.Map, java.io.Serializable

A custom implementation of the Map interface, where get and put calls try to access getter/setter methods of an associated UIComponent before falling back to accessing a real Map object.

Some of the behaviours of this class don't really comply with the definitions of the Map class; for example the key parameter to all methods is required to be of type String only, and after clear(), calls to get can return non-null values. However the JSF spec requires that this class behave in the way implemented below. See UIComponent.getAttributes for more details.

The term "property" is used here to refer to real javabean properties on the underlying UIComponent, while "attribute" refers to an entry in the associated Map.

Version:
$Revision: 394697 $ $Date: 2006-04-17 11:24:14 -0400 (Mon, 17 Apr 2006) $
Author:
Manfred Geiler (latest modification by $Author: schof $)

Nested Class Summary
 
Nested classes/interfaces inherited from interface java.util.Map
java.util.Map.Entry<K,V>
 
Constructor Summary
_ComponentAttributesMap(UIComponent component)
          Create a map backed by the specified component.
_ComponentAttributesMap(UIComponent component, java.util.Map attributes)
          Create a map backed by the specified component.
 
Method Summary
 void clear()
          Clear all the attributes in this map.
 boolean containsKey(java.lang.Object key)
          Return true if there is an attribute with the specified name, but false if there is a javabean property of that name on the associated UIComponent.
 boolean containsValue(java.lang.Object value)
          Returns true if there is an attribute with the specified value.
 java.util.Set entrySet()
          Return a set of all attributes.
 boolean equals(java.lang.Object obj)
          TODO: Document why this method is necessary, and why it doesn't try to compare the _component field.
 java.lang.Object get(java.lang.Object key)
          In order: get the value of a property of the underlying UIComponent, read an attribute from this map, or evaluate the component's value-binding of the specified name.
(package private)  java.util.Map getUnderlyingMap()
          Return the map containing the attributes.
 int hashCode()
           
 boolean isEmpty()
          Return true if there are no attributes in this map.
 java.util.Set keySet()
          Return a set of the keys for all attributes.
 java.lang.Object put(java.lang.Object key, java.lang.Object value)
          Store the provided value as a property on the underlying UIComponent, or as an attribute in a Map if no such property exists.
 void putAll(java.util.Map t)
          Call put(key, value) for each entry in the provided map.
 java.lang.Object remove(java.lang.Object key)
          Remove the attribute with the specified name.
 int size()
          Return the number of attributes in this map.
 java.util.Collection values()
          Return a collection of the values of all attributes.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

_ComponentAttributesMap

_ComponentAttributesMap(UIComponent component)
Create a map backed by the specified component.

This method is expected to be called when a component is first created.


_ComponentAttributesMap

_ComponentAttributesMap(UIComponent component,
                        java.util.Map attributes)
Create a map backed by the specified component. Attributes already associated with the component are provided in the specified Map class. A reference to the provided map is kept; this object's contents are updated during put calls on this instance.

This method is expected to be called during the "restore view" phase.

Method Detail

size

public int size()
Return the number of attributes in this map. Properties of the underlying UIComponent are not counted.

Note that because the get method can read properties of the UIComponent and evaluate value-bindings, it is possible to have size return zero while calls to the get method return non-null values.

Specified by:
size in interface java.util.Map

clear

public void clear()
Clear all the attributes in this map. Properties of the underlying UIComponent are not modified.

Note that because the get method can read properties of the UIComponent and evaluate value-bindings, it is possible to have calls to the get method return non-null values immediately after a call to clear.

Specified by:
clear in interface java.util.Map

isEmpty

public boolean isEmpty()
Return true if there are no attributes in this map. Properties of the underlying UIComponent are not counted.

Note that because the get method can read properties of the UIComponent and evaluate value-bindings, it is possible to have isEmpty return true, while calls to the get method return non-null values.

Specified by:
isEmpty in interface java.util.Map

containsKey

public boolean containsKey(java.lang.Object key)
Return true if there is an attribute with the specified name, but false if there is a javabean property of that name on the associated UIComponent.

Note that it should be impossible for the attributes map to contain an entry with the same name as a javabean property on the associated UIComponent.

Specified by:
containsKey in interface java.util.Map
Parameters:
key - must be a String. Anything else will cause a ClassCastException to be thrown.

containsValue

public boolean containsValue(java.lang.Object value)
Returns true if there is an attribute with the specified value. Properties of the underlying UIComponent aren't examined, nor value-bindings.

Specified by:
containsValue in interface java.util.Map
Parameters:
value - null is allowed

values

public java.util.Collection values()
Return a collection of the values of all attributes. Property values are not included, nor value-bindings.

Specified by:
values in interface java.util.Map

putAll

public void putAll(java.util.Map t)
Call put(key, value) for each entry in the provided map.

Specified by:
putAll in interface java.util.Map

entrySet

public java.util.Set entrySet()
Return a set of all attributes. Properties of the underlying UIComponent are not included, nor value-bindings.

Specified by:
entrySet in interface java.util.Map

keySet

public java.util.Set keySet()
Return a set of the keys for all attributes. Properties of the underlying UIComponent are not included, nor value-bindings.

Specified by:
keySet in interface java.util.Map

get

public java.lang.Object get(java.lang.Object key)
In order: get the value of a property of the underlying UIComponent, read an attribute from this map, or evaluate the component's value-binding of the specified name.

Specified by:
get in interface java.util.Map
Parameters:
key - must be a String. Any other type will cause ClassCastException.

remove

public java.lang.Object remove(java.lang.Object key)
Remove the attribute with the specified name. An attempt to remove an entry whose name is that of a property on the underlying UIComponent will cause an IllegalArgumentException. Value-bindings for the underlying component are ignored.

Specified by:
remove in interface java.util.Map
Parameters:
key - must be a String. Any other type will cause ClassCastException.

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)
Store the provided value as a property on the underlying UIComponent, or as an attribute in a Map if no such property exists. Value-bindings associated with the component are ignored; to write to a value-binding, the value-binding must be explicitly retrieved from the component and evaluated.

Note that this method is different from the get method, which does read from a value-binding if one exists. When a value-binding exists for a non-property, putting a value here essentially "masks" the value-binding until that attribute is removed.

The put method is expected to return the previous value of the property/attribute (if any). Because UIComponent property getter methods typically try to evaluate any value-binding expression of the same name this can cause an EL expression to be evaluated, thus invoking a getter method on the user's model. This is fine when the returned value will be used; Unfortunately this is quite pointless when initialising a freshly created component with whatever attributes were specified in the view definition (eg JSP tag attributes). Because the UIComponent.getAttributes method only returns a Map class and this class must be package-private, there is no way of exposing a "putNoReturn" type method.

Specified by:
put in interface java.util.Map
Parameters:
key - String, null is not allowed
value - null is allowed

getUnderlyingMap

java.util.Map getUnderlyingMap()
Return the map containing the attributes.

This method is package-scope so that the UIComponentBase class can access it directly when serializing the component.


equals

public boolean equals(java.lang.Object obj)
TODO: Document why this method is necessary, and why it doesn't try to compare the _component field.

Specified by:
equals in interface java.util.Map
Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Specified by:
hashCode in interface java.util.Map
Overrides:
hashCode in class java.lang.Object


Copyright 2006 Apache Software Foundation. All Rights Reserved.