com.sun.rave.web.ui.component.util
Class Util

java.lang.Object
  extended by com.sun.rave.web.ui.component.util.Util

public class Util
extends java.lang.Object

Utility class that contains helper methods for components.


Method Summary
static void addPhaseListener(javax.faces.event.PhaseListener phaseListener)
          Add a PhaseListener.
static javax.faces.component.UIComponent createChildComponent(javax.faces.context.FacesContext context, LayoutComponent descriptor, javax.faces.component.UIComponent parent)
           This method creates a child UIComponent by using the provided LayoutComponent (descriptor).
static javax.faces.component.UIComponent findChild(javax.faces.component.UIComponent parent, java.lang.String id, java.lang.String facetName)
           Return a child with the specified component id (or facetName) from the specified component.
static java.lang.String getActionURL(javax.faces.context.FacesContext context, java.lang.String url)
           
static java.lang.String getBase(javax.faces.context.FacesContext context)
          Return the base URI for the view identifier of the current view.
static javax.faces.component.UIComponent getChild(javax.faces.component.UIComponent parent, LayoutComponent descriptor)
           This method finds or creates a child UIComponent identified by the given id.
static javax.faces.component.UIComponent getChild(javax.faces.component.UIComponent parent, java.lang.String id)
           Return a child with the specified component id from the specified component.
static javax.faces.component.UIComponent getChild(javax.faces.component.UIComponent parent, java.lang.String id, java.lang.String factoryClass)
           This method finds or creates a child UIComponent identified by the given id.
static javax.faces.component.UIComponent getChild(javax.faces.component.UIComponent parent, java.lang.String id, java.lang.String factoryClass, java.util.Properties properties)
           This method finds or creates a child UIComponent identified by the given id.
static javax.faces.component.UIComponent getChild(javax.faces.component.UIComponent parent, java.lang.String id, java.lang.String factoryClass, java.util.Properties properties, java.lang.String facetName)
           Same as getChild(UIComponent, String, String, Properties) except that it allows you to specify a facetName different than the id.
static javax.faces.component.UIComponent getChild(javax.faces.component.UIComponent parent, java.lang.String id, java.lang.String factoryClass, java.lang.String facetName)
           Same as getChild(UIComponent, String, String) except that it allows you to specify a facetName different than the id.
static java.lang.String getContext(javax.faces.context.FacesContext context)
          Return an absolute URL to our server and context path.
static javax.faces.component.UIComponent getForm(javax.faces.context.FacesContext context, javax.faces.component.UIComponent component)
          Helper method to obtain containing UIForm.
static java.lang.String getFormName(javax.faces.context.FacesContext context, javax.faces.component.UIComponent component)
          Gets the form id from the containing UIForm.
static boolean isVisible(javax.faces.component.UIComponent component)
           Return whether the given UIComponent is "visible".
static void removePhaseListener(javax.faces.event.PhaseListener phaseListener)
          Remove a PhaseListener.
static java.lang.Object resolveValue(javax.faces.context.FacesContext context, LayoutElement elt, javax.faces.component.UIComponent parent, java.lang.String value)
           This method will attempt to resolve EL strings in the given value.
static java.lang.Object setOption(javax.faces.context.FacesContext context, java.lang.String key, java.lang.Object value, LayoutElement desc, javax.faces.component.UIComponent component)
           This util method will set the given key/value on the UIComponent.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getChild

public static javax.faces.component.UIComponent getChild(javax.faces.component.UIComponent parent,
                                                         java.lang.String id)

Return a child with the specified component id from the specified component. If not found, return null.

This method will NOT create a new UIComponent.

Parameters:
parent - UIComponent to be searched
id - Component id (or facet name) to search for
Returns:
The child UIComponent if it exists, null otherwise.

findChild

public static javax.faces.component.UIComponent findChild(javax.faces.component.UIComponent parent,
                                                          java.lang.String id,
                                                          java.lang.String facetName)

Return a child with the specified component id (or facetName) from the specified component. If not found, return null. facetName or id may be null to avoid searching the facet Map or the parent's children.

This method will NOT create a new UIComponent.

Parameters:
parent - UIComponent to be searched
id - id to search for
facetName - Facet name to search for
Returns:
The child UIComponent if it exists, null otherwise.

getChild

public static javax.faces.component.UIComponent getChild(javax.faces.component.UIComponent parent,
                                                         java.lang.String id,
                                                         java.lang.String factoryClass)

This method finds or creates a child UIComponent identified by the given id. If the child is not found, it will attempt to create it using the provided ComponentFactory (factoryClass).

If there are Properties to be set on the UIComponent, this method should generally be avoided. It is preferable to use the getChild(UIComponent, String, String, Properties) form of getChild.

// Example (no properties):
UIComponent child = Util.getChild(component, "jklLabel", "com.sun.rave.web.ui.component.util.factories.LabelFactory");
((Label)child).setText("JKL Label:");
((Label)child).setFor("jkl");

LayoutComponent.encodeChild(context, child);

Parameters:
parent - Parent UIComponent
id - Identifier for the child UIComponent
factoryClass - Full ComponentFactory class name
Returns:
The child UIComponent that was found or created.
See Also:
getChild(UIComponent, String, String, Properties)

getChild

public static javax.faces.component.UIComponent getChild(javax.faces.component.UIComponent parent,
                                                         java.lang.String id,
                                                         java.lang.String factoryClass,
                                                         java.lang.String facetName)

Same as getChild(UIComponent, String, String) except that it allows you to specify a facetName different than the id. If null is supplied, it won't save the component as a facet.

Parameters:
parent - Parent UIComponent
id - Identifier for the child UIComponent
factoryClass - Full ComponentFactory class name
facetName - The facet name (null means don't store it)
Returns:
The child UIComponent that was found or created.
See Also:
getChild(UIComponent, String, String)

getChild

public static javax.faces.component.UIComponent getChild(javax.faces.component.UIComponent parent,
                                                         java.lang.String id,
                                                         java.lang.String factoryClass,
                                                         java.util.Properties properties)

This method finds or creates a child UIComponent identified by the given id. If the child is not found, it will attempt to create it using the provided ComponentFactory (factoryClass). It will also initialize the UIComponent using the provided set of Properties.

// Example (with properties):
Properties props = new Properties();
props.setProperty("text", "ABC Label:");
props.setProperty("for", "abc");
UIComponent child = Util.getChild(component, "abcLabel", "com.sun.rave.web.ui.component.util.factories.LabelFactory", props);

LayoutComponent.encodeChild(context, child);

Parameters:
parent - Parent UIComponent
id - Identifier for the child UIComponent
factoryClass - Full ComponentFactory class name
properties - java.util.Properties needed to create and/or initialize the UIComponent
Returns:
The child UIComponent that was found or created.

getChild

public static javax.faces.component.UIComponent getChild(javax.faces.component.UIComponent parent,
                                                         java.lang.String id,
                                                         java.lang.String factoryClass,
                                                         java.util.Properties properties,
                                                         java.lang.String facetName)

Same as getChild(UIComponent, String, String, Properties) except that it allows you to specify a facetName different than the id. If null is supplied, it won't save the component as a facet.

Parameters:
parent - Parent UIComponent
id - Identifier for the child UIComponent
factoryClass - Full ComponentFactory class name
properties - java.util.Properties needed to create and/or initialize the UIComponent
facetName - The facet name (null means don't store it)
Returns:
The child UIComponent that was found or created.

getChild

public static javax.faces.component.UIComponent getChild(javax.faces.component.UIComponent parent,
                                                         LayoutComponent descriptor)

This method finds or creates a child UIComponent identified by the given id. If the child is not found, it will attempt to create it using the provided LayoutComponent (descriptor). It will also initialize the UIComponent using the options set on the LayoutComponent.

If parent implements ChildManager, then the responsibility of finding and creating the child will be delegated to the ChildManager UIComponent.

If you are constructing and populating a LayoutComponent before calling this method, there are a few features that should be noted. Besides id and type which can be set in the LayoutComponent constructor, you can also set options, and Handler's.

Options may be set via LayoutComponent.setOptions(Map). These options will be applied to the UIComponent and may also be used by the ComponentFactory while instantiating the UIComponent.

Handler's can be supplied by calling LayoutElementBase.setHandlers(String, List). The type must match the event name which invokes the List of handlers you provide. The Renderer for this UIComponent is responsible for declaring and dispatching events. TemplateRenderer will invoke beforeCreate and afterCreate events for each child it creates (such as the one being requested here).

// Example (with LayoutComponent):
ComponentType type = new ComponentType("LabelFactory", "com.sun.rave.web.ui.component.util.factories.LabelFactory");
LayoutComponent descriptor = new LayoutComponent(null, "abcLabel", type);
descriptor.addOption("text", "ABC Label:");
descriptor.addOption("for", "abc");
UIComponent child = Util.getChild(component, descriptor);

LayoutComponent.encodeChild(context, child);

Parameters:
parent - Parent UIComponent
descriptor - The LayoutComponent describing the UIComponent
Returns:
The child UIComponent that was found or created.

createChildComponent

public static javax.faces.component.UIComponent createChildComponent(javax.faces.context.FacesContext context,
                                                                     LayoutComponent descriptor,
                                                                     javax.faces.component.UIComponent parent)

This method creates a child UIComponent by using the provided LayoutComponent (descriptor). It will associate the parent and the newly created UIComponent.

It is recommended that this method NOT be called from a Renderer. It should not be called if you have not yet checked to see if a child UIComponent with the requested ID already exists.

Parameters:
context - The FacesContext object.
descriptor - The LayoutComponent describing the UIComponent to be created.
parent - Parent UIComponent.
Returns:
A new UIComponent based on the provided LayoutComponent.
Throws:
java.lang.IllegalArgumentException - Thrown if descriptor equals null.
See Also:
getChild(UIComponent, LayoutComponent), getChild(UIComponent, String, String, Properties), LayoutComponent.getType(), ComponentType.getFactory(), ComponentFactory.create(FacesContext, LayoutComponent, UIComponent)

setOption

public static java.lang.Object setOption(javax.faces.context.FacesContext context,
                                         java.lang.String key,
                                         java.lang.Object value,
                                         LayoutElement desc,
                                         javax.faces.component.UIComponent component)

This util method will set the given key/value on the UIComponent. It will resolve all $...{...} expressions, and convert the String into a ValueBinding if a ValueBinding is detected. The return value will be a ValueBinding or the value.

Parameters:
context - FacesContext
key - The Property name to set
value - The Property value to set
desc - The LayoutElement associated with the UIComponent
component - The UIComponent
Returns:
A ValueBinding, or the evaulated value (if no value binding is present).

getForm

public static javax.faces.component.UIComponent getForm(javax.faces.context.FacesContext context,
                                                        javax.faces.component.UIComponent component)

Helper method to obtain containing UIForm.

Parameters:
context - FacesContext for the request we are processing.
component - UIComponent to find form from.
Returns:
Returns the UIForm component that contains this element

getFormName

public static java.lang.String getFormName(javax.faces.context.FacesContext context,
                                           javax.faces.component.UIComponent component)

Gets the form id from the containing UIForm.

Parameters:
context - FacesContext for the request we are processing.
component - UIComponent to find form from.
Returns:
Returns the id of the UIForm that contains this element.

resolveValue

public static java.lang.Object resolveValue(javax.faces.context.FacesContext context,
                                            LayoutElement elt,
                                            javax.faces.component.UIComponent parent,
                                            java.lang.String value)

This method will attempt to resolve EL strings in the given value.

Parameters:
context - The FacesContext
elt - The LayoutElement associated w/ the expression
parent - The parent UIComponent. This is used because the current UIComponent is typically unknown (or not even created yet).
value - The String to resolve
Returns:
The evaluated value (may be null).

getBase

public static java.lang.String getBase(javax.faces.context.FacesContext context)

Return the base URI for the view identifier of the current view.

Parameters:
context - FacesContext for the current request

getContext

public static java.lang.String getContext(javax.faces.context.FacesContext context)

Return an absolute URL to our server and context path.

Parameters:
context - FacesContext for the current request

getActionURL

public static java.lang.String getActionURL(javax.faces.context.FacesContext context,
                                            java.lang.String url)

isVisible

public static boolean isVisible(javax.faces.component.UIComponent component)

Return whether the given UIComponent is "visible". If the property is null, it will return true. Otherwise the value of the property is returned.

Parameters:
component - The UIComponent to check
Returns:
True if the property is null or true, false otherwise.

addPhaseListener

public static void addPhaseListener(javax.faces.event.PhaseListener phaseListener)
Add a PhaseListener.

Parameters:
phaseListener - PhaseListener instance.

removePhaseListener

public static void removePhaseListener(javax.faces.event.PhaseListener phaseListener)
Remove a PhaseListener.

Parameters:
phaseListener - PhaseListener instance.