[jsr344-experts mirror] [jsr344-experts] UIComponent.getPassThroughAttributes() convenience method

  • From: Andy Schwartz <andy.schwartz@...>
  • To: JSF Experts <jsr344-experts@...>
  • Subject: [jsr344-experts mirror] [jsr344-experts] UIComponent.getPassThroughAttributes() convenience method
  • Date: Wed, 27 Feb 2013 14:41:57 -0500
  • List-id: <jsr344-experts.javaserverfaces-spec-public.java.net>

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 {@link javax.faces.render.Renderer}. This method must * never return {@code null}. The returned * {@code Map} implementation must support all of the standard and optional * {@code Map} methods, plus support the following additional requirements.</p> * * <div class="changed_added_2_2"> * * <p>The {@code Map} implementation must implement {@code java.io.Serializable}.</p> * * <p>Any attempt to add a {@code null} key or value must throw a {@code NullPointerExcep\
tion}.</p> * * <p>Any attempt to add a key that is not a {@code String} must * throw an {@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 * {@link #getPassThroughAttributes() } except that it is allowed to return * {@code null} if and only if the argument {@code create} is {@code false} * and no pass through attribute data structure exists for this instance.</p> * @param create if <code>true</code>, a new {@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 {@code Map} instance, or {@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.)


[jsr344-experts mirror] [jsr344-experts] UIComponent.getPassThroughAttributes() convenience method

Andy Schwartz 02/27/2013

[jsr344-experts mirror] [jsr344-experts] [1111-PassThoughElements] Additional work

Edward Burns 02/28/2013
Terms of Use; Privacy Policy; Copyright ©2013-2017 (revision 20160708.bf2ac18)
Please Confirm