Minor API issue that I ran into when attempting to build Trinidad/ADF
Faces against JSF 2.2. (Yes, I am finally looking at 2.2.)
UIComponent defines two overloads of getPassThroughAttributes():
>
> /**
>
> * <p class="changed_added_2_2">Return a data structure containing
> the attributes
> * of this component that should be rendered directly to the
> output without
> * interpretation by the {_at_link javax.faces.render.Renderer}.
> This method must
> * never return {_at_code null}. The
> returned
> * {_at_code Map} implementation must support all of the standard and
> optional
> * {_at_code Map} methods, plus support the following additional
> requirements.</p>
>
> *
>
> * <div
> class="changed_added_2_2">
>
>
> *
>
> * <p>The {_at_code Map} implementation must implement {_at_code
> java.io.Serializable}.</p>
>
> *
>
> * <p>Any attempt to add a {_at_code null} key or value must throw a
> {_at_code NullPointerExcep\
> tion}.</p>
>
>
> *
>
> * <p>Any attempt to add a key that is not a {_at_code String}
> must
> * throw an {_at_code
> IllegalArgumentException}.</p>
>
> *
>
> *
> </div>
>
>
> *
>
> * @since
> 2.2
>
> */
>
> public abstract Map<String, Object> getPassThroughAttributes();
>
>
>
> /**
>
> * <p class="changed_added_2_2">This method has the same
> specification as
> * {_at_link #getPassThroughAttributes() } except that it is allowed
> to return
> * {_at_code null} if and only if the argument {_at_code create} is
> {_at_code false}
> * and no pass through attribute data structure exists for this
> instance.</p>
>
>
> * @param create if <code>true</code>, a new {_at_code
> Map}
> * instance will be created if it does not exist already.
> If
> * <code>false</code>, and there is no
> existing
> * <code>Map</code> instance, one will not be created
> and
> * <code>null</code> will be
> returned.
> * @return A {_at_code Map} instance, or {_at_code
> null}.
>
> *
>
> * @since
> 2.2
>
> */
>
> public abstract Map<String, Object>
> getPassThroughAttributes(boolean create);
The first form is merely a convenience method for:
> public Map<String, Object> getPassThroughAttributes() {
>
> return getPassThroughAttributes(true);
> }
We should make the no-arg convenience method final and include the
trivial implementation in UIComponent.
This makes the role of these two methods clear: the boolean overload
provides the implementation, and the no-arg overload is a trivial
convenience method.
We should probably swap the javadoc around so that the main
documentation is on the boolean method. The javadoc for the no-arg
method can be simplified to state that it is a convenience for
getPassThroughAttributes(true).
Let me know if I should file an issue for this. (Or if there is any
disagreement over this API design pattern.)
Andy