Skip to main content

JSF2 Composite Component Metadata

Posted by edburns on September 2, 2009 at 12:53 PM EDT

This ultra-quick blog entry shows how to use the JSF runtime to access metadata for a composite component. Note that most of the metadata is optional when creating a composite component, therefore, this entry will be of interest to tool vendors and those wishing to write composite components that stand a chance of showing up nicely in tools.

The Using Page

When showing a composite component demo, I always like to start out with the using page.

Listing 1: the using page

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  2. <html xmlns="http://www.w3.org/1999/xhtml"
  3.      xmlns:h="http://java.sun.com/jsf/html"
  4.      xmlns:f="http://java.sun.com/jsf/core"
  5.      xmlns:my="http://java.sun.com/jsf/composite/cc"
  6.      xmlns:meta="http://mojarra.dev.java.net/cc-metadata">
  7. <h:head>
  8.   <title>A Simple JavaServer Faces 2.0 View</title>
  9. <style type="text/css">
  10. .grayBox { padding: 8px; margin: 10px 0; border: 1px solid #CCC; background-color: #f9f9f9;  }
  12.  
  13. </h:head>
  14. <h:body>
  15.   <h:form>
  16.  
  17.     <p>Composite Component usage:</p>
  18.  
  19. <div id="cc" class="grayBox" style="border: 1px solid #090;">
  20. <my:myComponent loginAction="#{userBean.loginAction}" />
  21. </div>
  22.  
  23. <h2>Metada for This Composite Component</h2>
  24.  
  25. <div id="foo" class="grayBox" style="border: 1px solid #090;">
  26.     <pre>
  27.     <meta:printMetadata viewName="main.xhtml" libraryName="cc"
  28.                        resourceName="myComponent.xhtml"/>
  29.     </pre>
  30. </div>
  31.  
  32.  
  33.     <p><h:commandButton value="submit" /></p>
  34.   </h:form>
  35. </h:body>
  36. </html>
  37.  

Line 5 declares the namespace “my” using the handy composite component namespace prefix “http://java.sun.com/jsf/composite” followed by “cc”. JSF 2 interprets this to mean: treat any .xhtml files in the directory /resources/cc as a JSF composite component.

Line 6 declares a Facelet custom tag library with the namespace “http://mojarra.dev.java.net/cc-metadata”.

Line 20 uses the composite component named “myComponent” in the “cc” library.

Line 27 uses the “printMetadata” component from the Facelet custom tag library. We must pass in the name of a Facelet page, the library name, and the resource name.

The Composite Component

Let's examine the composite component itself. As I mentioned earlier, most of this metadata is optional and is included here just to show what the system understands. This component has just about every kind of metadata that is in the JSF2 spec.

Listing 2 the composite component

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  2. <html xmlns="http://www.w3.org/1999/xhtml"
  3.      xmlns:h="http://java.sun.com/jsf/html"
  4.      xmlns:f="http://java.sun.com/jsf/core"
  5.      xmlns:ui="http://java.sun.com/jsf/facelets"
  6.      xmlns:fmd="http://java.sun.com/xml/ns/javaee/faces/design-time-metadata"
  7.      xmlns:cc="http://java.sun.com/jsf/composite">
  9.  
  10. <title>Not present in rendered output</title>
  11.  
  12. </head>
  13.  
  15.  
  16. <cc:interface
  17.    name="component"
  18.    displayName="A really fancy composite component"
  19.    expert="true"
  20.    hidden="false"
  21.    preferred="true"
  22.    shortDescription="This component has all the supported metadata."
  23.    extraTopLevelAttribute="Whatever I want here">
  24.  
  25. <!-- start top level attributes -->
  26.  
  27.   <cc:attribute
  28.    name="model"
  29.    required="true"
  30.    displayName="model"
  31.    expert="false"
  32.    hidden="false"
  33.    preferred="true"
  34.    shortDescription="The model for this component"
  35.    extraTopLevelAttribute="Whatever I want here">
  36.     <cc:extension>
  37.       <fmd:expert>true</fmd:expert>
  38.     </cc:extension>
  39.     <cc:attribute
  40.      name="userid"
  41.      default="guest"
  42.      displayName="User Id"
  43.      expert="false"
  44.      hidden="false"
  45.      preferred="true"
  46.      shortDescription="The model must have a userid property"/>
  47.     <cc:attribute
  48.      name="password"
  49.      default="guest"
  50.      displayName="Password"
  51.      expert="false"
  52.      hidden="false"
  53.      preferred="true"
  54.      shortDescription="The model must have a password property"/>
  55.   </cc:attribute>
  56.  
  57.   <cc:attribute name="useridLabel" default="Userid:" />
  58.  
  59.   <cc:attribute name="passwordLabel" default="Password:" />
  60.  
  61.   <cc:attribute name="loginButtonLabel" default="Login" />
  62.  
  63.   <cc:attribute name="loginAction" method-signature="java.lang.String f()"
  64.    required="true" />
  65.  
  66. <!-- end top level attributes -->
  67.  
  68. <!-- start facets -->
  69.  
  70.   <cc:facet
  71.    name="header"
  72.    displayName="The header facet for the fancy component"
  73.    expert="true"
  74.    hidden="false"
  75.    preferred="false"
  76.    shortDescription="If you want a header, this is where you put it"
  77.    anotherExtraAttribute="Lots of metadata" />
  78.  
  79.   <cc:facet
  80.    name="footer"
  81.    displayName="The footer facet for the fancy component"
  82.    expert="true"
  83.    hidden="false"
  84.    preferred="false"
  85.    shortDescription="If you want a footer, this is where you put it"
  86.    anotherExtraAttribute="Lots of metadata" />
  87.  
  88. <!-- end facets -->
  89.  
  90. <!-- start attached objects -->
  91.  
  92.   <cc:editableValueHolder
  93.    name="userid"
  94.    displayName="Userid field"
  95.    expert="true"
  96.    hidden="false"
  97.    preferred="false"
  98.    shortDescription="Attach a converter or validator here, if you like"
  99.    someExtraMetadata="userid metadata" />
  100.  
  101.   <cc:editableValueHolder
  102.    name="password"
  103.    displayName="Password field"
  104.    expert="true"
  105.    hidden="false"
  106.    preferred="false"
  107.    shortDescription="Attach a converter or validator here, if you like"
  108.    someExtraMetadata="password metadata" />
  109.  
  110.   <cc:actionSource
  111.    name="login"
  112.    displayName="Login button"
  113.    expert="true"
  114.    hidden="false"
  115.    preferred="false"
  116.    shortDescription="Attach an actionListener here, if you like"
  117.    someExtraMetadata="login metadata" />
  118.  
  119. <!-- end attached objects -->
  120.  
  121. </cc:interface>
  122.  
  123. <cc:implementation>
  124.  
  125.   <cc:renderFacet name="header" />
  126.  
  127.   <p><h:outputLabel for="#{cc.clientId}:userid"
  128.                    value="#{cc.attrs.useridLabel}" />
  129.      <h:inputText id="userid" /></p>
  130.  
  131.   <p><h:outputLabel for="#{cc.clientId}:password"
  132.                    value="#{cc.attrs.passwordLabel}" />
  133.      <h:inputText id="password" /></p>
  134.  
  135.   <p><h:commandButton value="#{cc.attrs.loginButtonLabel}"
  136.                      action="#{cc.attrs.loginAction}" /></p>
  137.  
  138.   <cc:renderFacet name="footer" />
  139.  
  140.  
  141. </cc:implementation>
  142.  
  143. </body>
  144.  
  145. </html>
  146.  

Lines 16 - 23 declare the top level composite component metadata.

Lines 25 - 65 declare the attributes that may be passed as XML elements on the composite component instance in the using page. Note that the loginAction attribute is declared as required on line 63. This is useful because Facelets will put up a helpful error if the page author doesn't supply a value here.

Lines 68 - 88 declare the allowable facets. In this case, they're optional.

Lines 90 - 119 declare the attached objects within the implementation section that are publically accessible from the using page.

Programmatically accessing the metadata

Up to this point, everything I've shown has been included in other blog entries elsewhere. What hasn't been shown is how the JSF runtime uses the metadata API to actually conjure up the composite component instance. This API is also accessible to tools that want to embed a JSF runtime into their tool environment. To show this off, I've created a non-composite JSF component and exposed it in the usual way, with a Facelet taglib. This still requires a descriptor, which is placed in WEB-INF/classes/META-INF.

Listing 3 the cc-metadata.taglib.xml

  1. <facelet-taglib  xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
  2.   xmlns='http://java.sun.com/xml/ns/javaee'
  3.   xsi:schemaLocation='http://java.sun.com/xml/ns/javaee web-facelettaglibrary_2_0.xsd'
  4.   version="2.0">
  5.     <namespace>http://mojarra.dev.java.net/cc-metadata</namespace>
  6.     <tag>
  7.         <tag-name>printMetadata</tag-name>
  8.         <component>
  9.             <component-type>jsf2.PrintMetadata</component-type>
  10.         </component>
  11. <!-- these are advisory and not enforced by the runtime -->
  12.         <attribute>
  13.             <name>viewName</name>
  14.             <required>true</required>
  15.         </attribute>
  16.         <attribute>
  17.             <name>libraryName</name>
  18.             <required>true</required>
  19.         </attribute>
  20.         <attribute>
  21.             <name>resourceName</name>
  22.             <required>true</required>
  23.         </attribute>
  24.     </tag>
  25.  
  26. </facelet-taglib>

Lines 11 - 23 are optional but I like to include them for explicit documentation.

The JSF Component that shows how to access the metadata is in Listing 4 A. This listing covers obtaining a reference to the BeanInfo that is the composite component metadata.

Listing 4 A, Accessing the composite component metadata programmatically

  1. package jsf2;
  2.  
  3. import java.beans.BeanInfo;
  4. import java.io.IOException;
  5. import javax.faces.FacesException;
  6. import javax.faces.application.Resource;
  7. import javax.faces.component.FacesComponent;
  8. import javax.faces.component.UIOutput;
  9. import javax.faces.context.FacesContext;
  10. import javax.faces.context.ResponseWriter;
  11. import javax.faces.view.ViewDeclarationLanguage;
  12.  
  13. @FacesComponent(value="jsf2.PrintMetadata")
  14. public class PrintMetadata extends UIOutput {
  15.  
  16.     @Override
  17.     public void encodeAll(FacesContext context) throws IOException {
  18.         ResponseWriter writer = context.getResponseWriter();
  19.         String
  20.                 viewName,
  21.                 libraryName,
  22.                 resourceName;
  23.  
  24.         try {
  25.             viewName = this.getAttributes().get("viewName").toString();
  26.             libraryName = this.getAttributes().get("libraryName").toString();
  27.             resourceName = this.getAttributes().get("resourceName").toString();
  28.         } catch (NullPointerException e) {
  29.             throw new FacesException("Must supply viewName, libraryName and resourceName attributes");
  30.         }
  31.  
  32.         ViewDeclarationLanguage vdl = context.getApplication().
  33.                 getViewHandler().getViewDeclarationLanguage(context, viewName);
  34.         Resource compositeComponentResource = context.getApplication().getResourceHandler().createResource(resourceName, libraryName);
  35.  
  36.         BeanInfo metadata = vdl.getComponentMetadata(context, compositeComponentResource);
  37.  
  38.         CompositeComponentMetadataUtils.writeMetadata(metadata, writer);
  39.  
  40.     }
  41. }
  42.  

On lines 24 - 29 we extract the required attributes that have been passed to us via the page author.

On line 32, we obtain a reference to the ViewDeclarationLanguage instance for Facelets.

On line 34, we create a Resource instance using the passed in composite component library name and resource name.

Line 36 features the call o getComponentMetadata(). It is safe to call this method only during the context of the JSF request processing lifecycle. Because we're doing it from inside the rendering of a component, we know that this is such a context.

Finally, Listing 4 B shows a traversal of the metadata.

Listing 4 B, what you can do with the metadata

  1. package jsf2;
  2.  
  3. import java.beans.BeanDescriptor;
  4. import java.beans.BeanInfo;
  5. import java.beans.FeatureDescriptor;
  6. import java.beans.PropertyDescriptor;
  7. import java.io.IOException;
  8. import java.util.Enumeration;
  9. import java.util.List;
  10. import java.util.Map;
  11. import javax.el.ValueExpression;
  12. import javax.faces.component.UIComponent;
  13. import javax.faces.context.FacesContext;
  14. import javax.faces.context.ResponseWriter;
  15. import javax.faces.view.AttachedObjectTarget;
  16.  
  17. public class CompositeComponentMetadataUtils {
  18.  
  19.     /**
  20.      * <p>Use the composite component metadata specification
  21.      * in section JSF.3.6.2.1 to print out the metadata to
  22.      * the argument writer.</p>
  23.      * @throws IOException
  24.      */
  25.  
  26.     public static void writeMetadata(BeanInfo metadata,
  27.             ResponseWriter writer) throws IOException{
  28.  
  29.         // Print out the top level BeanDescriptor stuff.
  30.         BeanDescriptor descriptor = metadata.getBeanDescriptor();
  31.         writeFeatureDescriptor("composite-component-BeanDescriptor", descriptor,
  32.                 writer);
  33.         writeFeatureDescriptorValues(
  34.                 "composite-component-BeanDescriptor", descriptor,
  35.                 writer);
  36.         PropertyDescriptor attributes[] = metadata.getPropertyDescriptors();
  37.         for (PropertyDescriptor cur : attributes) {
  38.             writeFeatureDescriptor("composite-component-attribute", cur,
  39.                     writer);
  40.             writeFeatureDescriptorValues("composite-component-attribute", cur,
  41.                     writer);
  42.         }
  43.     }
  44.  
  45.     public static void writeFeatureDescriptor(String prefix,
  46.             FeatureDescriptor fd, ResponseWriter writer) throws IOException {
  47.  
  48.         writer.write(prefix + "-name:" +
  49.                 fd.getName() + "\n");
  50.         writer.write(prefix + "-displayName:" +
  51.                 fd.getDisplayName() + "\n");
  52.         writer.write(prefix + "-shortDescription:" +
  53.                 fd.getShortDescription() + "\n");
  54.         writer.write(prefix + "-expert:" +
  55.                 fd.isExpert() + "\n");
  56.         writer.write(prefix + "-hidden:" +
  57.                 fd.isHidden() + "\n");
  58.         writer.write(prefix + "-preferred:" +
  59.                 fd.isPreferred() + "\n");
  60.  
  61.     }
  62.  
  63.     public static void writeFeatureDescriptorValues(String prefix,
  64.             FeatureDescriptor fd, ResponseWriter writer) throws IOException {
  65.  
  66.         Enumeration<String> extraValues = fd.attributeNames();
  67.         String curName;
  68.         while (extraValues.hasMoreElements()) {
  69.             curName = extraValues.nextElement();
  70.             if (curName.equals(AttachedObjectTarget.ATTACHED_OBJECT_TARGETS_KEY)) {
  71.                 List<AttachedObjectTarget> attachedObjects =
  72.                         (List<AttachedObjectTarget>) fd.getValue(curName);
  73.                 for (AttachedObjectTarget curTarget : attachedObjects) {
  74.                     writer.write(prefix + "-attached-object-" + curTarget.getName() + "\n");
  75.                 }
  76.             } else if (curName.equals(UIComponent.FACETS_KEY)) {
  77.                 Map<String, PropertyDescriptor> facets =
  78.                         (Map<String, PropertyDescriptor>) fd.getValue(curName);
  79.                 for (String cur : facets.keySet()) {
  80.                     String facetPrefix = prefix + "-facet-" + cur;
  81.                     writeFeatureDescriptor(facetPrefix, facets.get(cur),
  82.                             writer);
  83.                     writeFeatureDescriptorValues(facetPrefix,
  84.                             facets.get(cur), writer);
  85.                 }
  86.             } else {
  87.                 ValueExpression ve = (ValueExpression) fd.getValue(curName);
  88.                 writer.write(prefix + "-extra-attribute-" + curName + ": " +
  89.                         ve.getValue(FacesContext.getCurrentInstance().getELContext())
  90.                         + "\n");
  91.             }
  92.         }
  93.     }
  94.  
  95.  
  96. }
  97.  

On line 30, we ask the argument BeanInfo for its BeanDescriptor. We pass this to the helper method writeFeatureDescriptor(). This simple method just prints out the standard FeatureDescriptor metadata.

On line 33, we pass the same descriptor to the helper method writeFeatureDescriptorValues(). This method steps through the Enumeration returned from attributeNames(), calls getValue() on each entry, and takes appropriate action on each entry, based on the metadata specification. Currently there are three kinds of entries.

  • Lines 70 - 75 deal with the attached objects. The type for this entry is List<AttachedObjectTarget>. AttachedObjectTarget encapsulates how an attached object, in this declared on lines 90 through 119 of Listing 1, exposes an inner component to the page author.

  • Lines 76 - 85 deal with the exposed facets. The type for this entry is Map<String, PropertyDescriptor>, where the key is the facet name and the PropertyDescriptor represents each individual <cc:facet> element. These are on lines 68 - 88 of Listing 1.

  • Lines 87 - 91 deal with the else case, which can be characterized as “if it's not the attached objects, and it's not the facets, then it'll just come to you as a ValueExpression.

Back up on line 36, we ask the metadata for the PropertyDescriptor [] using getPropertyDescriptors(). This is specified to return a PropertyDescritor for each of the attributes, in this case show on lines 25 - 64 of Listing 1. For each attribute, we print out the FeatureDescriptor and the values. However, note that in the case of attributes, there will only be ValueExpression instances in the getValue() data structure. A screengrab of the running page is show here.

screen grab of page showing component metadata

When the Expert Group designed this api, we wanted to make it as easy as possible to provide tool support for composite components. I hope this is helpful to tool authors for this purpose.

Technorati Tags:

Related Topics >>
Blog Links >>

Comments

&nbsp;Hi, In first thanks for this article and sorry for my ...

by adrien5 - 2011-08-17 12:56

Hi,

In first thanks for this article and sorry for my english.

I have a question about composite, I would like to create composite 'autonome'. So I have some difficulities to initialize it.

For example, i take a composite to edit a user like :

<mycomposite userId="theidOfTheUserToShow">

and for implementation

<composite:interface>

<composite:attribute name="userId" required="true" />

</composite:interface>

<composite:implementation>

Edit : #{ctrlEditUser.username} ....

</.....>

My problem is what is the best way to initialize backean? There is a way to do #{ctrlEditUser.init(userId)}, or anything way?

Thanks

In JSF 2.2, we'll have UIViewAction and the ...

by edburns - 2011-08-17 15:18

In JSF 2.2, we'll have UIViewAction and the <f:viewAction> tag. 

In JSF 2.1 and 2.0 you can use f:event, as shown in this demo:

svn.java.net/svn/mojarra~svn/trunk/jsf-ri/systest/web/viewParameters/events.xhtml

Which is included from

svn.java.net/svn/mojarra~svn/trunk/jsf-ri/systest/web/viewParameters/page02.xhtml

 

Is there a doc tool for this yet?

by jaxent - 2010-03-04 12:13

The Tag Library Document Generator doesn't work against either taglib.xml or Composite component metadata that I have been able to see.

about layout

by mcalpay - 2009-10-26 08:20

One common composite component I used with jsf 1.2 + facelets is : Which I use it like :