WidgetDefinitionParser

java.lang.Object
- com.ibm.commerce.pagelayout.widget.management.WidgetDefinitionParser

```
public class WidgetDefinitionParser
extends java.lang.Object
```
This class parses the XML definition of the widget to extract the following information:
- Configurable slots available in the widget. This is applicable for container widgets.
- Pre-configured properties of the widget.
- Widget manager class name.
- Supported device classes.
The XML is free-form and hence validation is not enforced on the parser. However, the parser expects the root element to be the Definition element. Under the root element, the parser by default reads the following elements:
- slot - This element is used to define configurable slots for the widget in case is a container widget. By default, all slots can be edited. The slot element is defined as follows:
```
 <slot internalSlotId="bodySlot1" slotType="ReadOnly"/>
 
```
- widget-property - This element is used to define the properties of the widget. A widget property can either take a single value or a list of values. For this purpose, the element can be defined with a single value as an attribute or a list of value elements whose text content is the value of the property. A property can define its data type using the type attribute. The list of supported types are all the primitive data types and string. A property can also define if it's required to have a value.
```
 A single value property: 
 <widget-property name="property1" required="true" type="java.lang.Integer" value="1"/>
 
 A multi value property:
 <widget-property name="property1" required="true" type="java.lang.Integer" >
        <value>1</value>
        <value>2</value>
 </widget-property>
 
```
- widget-manager - The element is used to define the widget manager class. A widget can have two managers based on the execution environment. The widget manager element is optional and can be omitted if the widget does not require any special mediation during its life-cycle on a page layout.
```
 <widget-manager j2se="com.ibm.commerce.pagelayout.widget.manager.J2SEWidgetManager" 
 j2ee="com.ibm.commerce.pagelayout.widget.manager.J2EEWidgetManager"/>
 
```
- suppported-device-class - This element is used to define the device types supported by the widget. If the element is not defined, the widget is applicable for all device types.
```
 <suppported-device-class>
        <value>Web</value>
 </suppported-device-class>
 
```
After the parse method is invoked, the methods getWidgetPropertiesDefined and getSlotsDefined should be used to retrieve the widget properties and configurable slots respectively. The widget manager class is returned as a property in the widget properties. The property name is PageLayoutFacadeConstants.WIDGETMANAGER_PROPERTY_NAME. The supported device classes for the widget are also returned as widget property. The property name is PageLayoutFacadeConstants.SUPPORTED_DEVICE_CLASSES_PROPERTY_NAME

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`COPYRIGHT` Copyright field.
`static java.lang.String`	`DEFINITION_ELEMENT_NAME` The tag name for the root element of the widget definition.
`protected static java.util.List<WidgetPropertyType>`	`EMPTY_WIDGET_PROPERTY_LIST` An empty list of widget properties.
`static java.lang.String`	`ID_ATTRIBUTE` The attribute used to define the id of the element.
`static java.lang.String`	`INTERNAL_SLOT_ID_ATTRIBUTE` The name of the attribute used to define the internal slot ID for the slot.
`static java.lang.String`	`NAME_ATTRIBUTE` The attribute used to define the name of the widget property.
`static java.lang.String`	`POSITIONAL_PROPERTY_LEFT` The attribute name for the positional property `left` for slots.
`static java.lang.String`	`POSITIONAL_PROPERTY_TOP` The attribute name for the positional property `top` for slots.
`static java.lang.String`	`POSITIONAL_PROPERTY_X` The attribute name for the positional property `x` for slots.
`static java.lang.String`	`POSITIONAL_PROPERTY_Y` The attribute name for the positional property `y` for slots.
`static java.lang.String`	`SLOT_ELEMENT_NAME` The element name for defining the configurable slots offered by the widget.
`static java.lang.String`	`SLOT_TYPE_ATTRIBUTE` The name of the attribute used to define the type of slot.
`static java.lang.String`	`SUPPORTED_DEVICE_CLASS_ELEMENT_NAME` The element name for defining the device classes supported by the widget.If the widget supports a single device class, it can define a `value` attribute.
`static java.lang.String`	`VALUE_NODE` This tag is used to define the value for the widget property.
`static java.lang.String`	`WIDGET_MANAGER_ELEMENT_NAME` The tag used to define the widget's manager class name.
`static java.lang.String`	`WIDGET_PROPERTY_ELEMENT_NAME` The element name for defining the properties of the widget.

Constructor Summary

Constructors
Constructor and Description

WidgetDefinitionParser()
Default constructor

WidgetDefinitionParser(WidgetDefinitionType widgetDefinition)
Constructor for the parser.

Constructors
Constructor and Description
`WidgetDefinitionParser()` Default constructor
`WidgetDefinitionParser(WidgetDefinitionType widgetDefinition)` Constructor for the parser.

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`addSlot(GenericSlotType slot)` This method adds a slot instance to the list of slots defined.
`protected void`	`addWidgetProperties(java.util.List<WidgetPropertyType> properties)` This method adds to the list of widget properties.
`protected GenericSlotType`	`createSlotFromElement(org.w3c.dom.Element slotElement)` This method creates a GenericSlot object from the `slot` element specified.
`protected java.util.List<WidgetPropertyType>`	`createSupportedDeviceClassWidgetProperty(org.w3c.dom.Element supportedDeviceClass)` This method creates the widget properties that indicate the supported device classes for the widget from the `supported-device-class` element specified.
`protected java.util.List<WidgetPropertyType>`	`createWidgetPropertyFromElement(org.w3c.dom.Element propertyElement)` This method creates the WidgetProperty from the `widget-property` element specified.
`protected java.lang.String`	`createXML(java.util.Map<java.lang.String,java.util.Map<java.lang.String,org.w3c.dom.Node>> dom)` This method creates the XML structure from the passed java object.
`java.lang.String`	`getDataTypeForProperty(java.lang.String propertyName)` This method indicates the data type of the property specified.
`protected org.w3c.dom.Document`	`getDocument(java.lang.String xml)` Given a XML, this method returns the Document representation of that XML.
`java.util.Set<java.lang.String>`	`getMandatoryWidgetProperties()` This method returns all the widget property names that are marked mandatory.
`protected PageLayoutFactory`	`getPageLayoutFactory()` Returns the instance of PageLayoutFactory to use for constructing SDOs.
`java.util.List<GenericSlotType>`	`getSlotsDefined()` Returns the slots defined in the widget's XML definition.
`protected WidgetDefinitionType`	`getWidgetDefinition()` Returns the widget definition object.
`java.util.List<WidgetPropertyType>`	`getWidgetPropertiesDefined()` Returns the list of widget properties defined for the widget.
`java.lang.Boolean`	`isMandatoryProperty(java.lang.String propertyName)` This method indicates if the property specified is required or not.
`java.lang.String`	`mergeXML(java.lang.String xml1, java.lang.String xml2)` Given 2 XML definitions, this method merges both the XML's and returns the final merged XML.
`void`	`parse()` This method parses the widget's XML definition to extract the configurable slots, widget properties and the widget manager class.
`protected void`	`updateDOM(java.lang.String defXML, java.util.Map<java.lang.String,java.util.Map<java.lang.String,org.w3c.dom.Node>> dom)` This method parses the defXML and then updates the passed java object with the result of parsing.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - COPYRIGHT
```
public static final java.lang.String COPYRIGHT
```
    Copyright field.
    
    See Also:
    
    Constant Field Values
  - SLOT_TYPE_ATTRIBUTE
```
public static final java.lang.String SLOT_TYPE_ATTRIBUTE
```
    The name of the attribute used to define the type of slot. It is used in the slot elements of the widget's XML definition.
    
    See Also:
    
    Constant Field Values
  - INTERNAL_SLOT_ID_ATTRIBUTE
```
public static final java.lang.String INTERNAL_SLOT_ID_ATTRIBUTE
```
    The name of the attribute used to define the internal slot ID for the slot. It is used in the slot elements of the widget's XML definition.
    
    See Also:
    
    Constant Field Values
  - VALUE_NODE
```
public static final java.lang.String VALUE_NODE
```
    This tag is used to define the value for the widget property. A widget property value can either be defined as an attribute (if its a single value attribute) or as value elements (if the property takes multiple values). The text content of the value node is the value of the widget property.
    
    See Also:
    
    Constant Field Values
  - NAME_ATTRIBUTE
```
public static final java.lang.String NAME_ATTRIBUTE
```
    The attribute used to define the name of the widget property. It is used in the widget property elements of the widget's XML definition.
    
    See Also:
    
    Constant Field Values
  - ID_ATTRIBUTE
```
public static final java.lang.String ID_ATTRIBUTE
```
    The attribute used to define the id of the element.
    
    See Also:
    
    Constant Field Values
  - WIDGET_MANAGER_ELEMENT_NAME
```
public static final java.lang.String WIDGET_MANAGER_ELEMENT_NAME
```
    The tag used to define the widget's manager class name. The tag takes two attributes namely j2se and j2ee whose values represent the widget manager class to be used based on the execution environment.
    
    See Also:
    
    Constant Field Values
  - WIDGET_PROPERTY_ELEMENT_NAME
```
public static final java.lang.String WIDGET_PROPERTY_ELEMENT_NAME
```
    The element name for defining the properties of the widget. A widget property element takes a name attribute. If the property takes a single value, the element can define a value attribute. If the property takes multiple values, the element can define a list of value nodes.
    
    See Also:
    
    Constant Field Values
  - SLOT_ELEMENT_NAME
```
public static final java.lang.String SLOT_ELEMENT_NAME
```
    The element name for defining the configurable slots offered by the widget. This element accepts internalSlotId, slotType as attributes.
    
    See Also:
    
    Constant Field Values
  - SUPPORTED_DEVICE_CLASS_ELEMENT_NAME
```
public static final java.lang.String SUPPORTED_DEVICE_CLASS_ELEMENT_NAME
```
    The element name for defining the device classes supported by the widget.If the widget supports a single device class, it can define a value attribute. If the widget supports multiple device classes, it can define a list of value nodes.
    
    See Also:
    
    Constant Field Values
  - DEFINITION_ELEMENT_NAME
```
public static final java.lang.String DEFINITION_ELEMENT_NAME
```
    The tag name for the root element of the widget definition. The parser checks for this element to consider the XML valid.
    
    See Also:
    
    Constant Field Values
  - POSITIONAL_PROPERTY_X
```
public static final java.lang.String POSITIONAL_PROPERTY_X
```
    The attribute name for the positional property x for slots.
    
    See Also:
    
    Constant Field Values
  - POSITIONAL_PROPERTY_Y
```
public static final java.lang.String POSITIONAL_PROPERTY_Y
```
    The attribute name for the positional property y for slots.
    
    See Also:
    
    Constant Field Values
  - POSITIONAL_PROPERTY_TOP
```
public static final java.lang.String POSITIONAL_PROPERTY_TOP
```
    The attribute name for the positional property top for slots.
    
    See Also:
    
    Constant Field Values
  - POSITIONAL_PROPERTY_LEFT
```
public static final java.lang.String POSITIONAL_PROPERTY_LEFT
```
    The attribute name for the positional property left for slots.
    
    See Also:
    
    Constant Field Values
  - EMPTY_WIDGET_PROPERTY_LIST
```
protected static final java.util.List<WidgetPropertyType> EMPTY_WIDGET_PROPERTY_LIST
```
    An empty list of widget properties. Use this while returning a empty list from createWidgetPropertyFromElement(Element) method.
- Constructor Detail
  - WidgetDefinitionParser
```
public WidgetDefinitionParser(WidgetDefinitionType widgetDefinition)
```
    Constructor for the parser.
    
    Parameters:
    
    widgetDefinition - The widget whose XML definition is being parsed.
  - WidgetDefinitionParser
```
public WidgetDefinitionParser()
```
    Default constructor
- Method Detail
  - parse
```
public void parse()
           throws WidgetDefinitionException
```
    This method parses the widget's XML definition to extract the configurable slots, widget properties and the widget manager class. The method validates if the root element of the XML definition is the DEFINITION_ELEMENT_NAME before parsing.
    
    Throws:
    
    WidgetDefinitionException - When the parsing fails due malformed XML.
    
    See Also:
    
    WidgetDefinitionParser#createSlotFromElement(Element)}, WidgetDefinitionParser#createWidgetPropertyFromElement(Element)}
  - getDocument
```
protected org.w3c.dom.Document getDocument(java.lang.String xml)
                                    throws WidgetDefinitionException
```
    Given a XML, this method returns the Document representation of that XML. If the root element of the XML is not , then an exception will be thrown.
    
    Parameters:
    
    xml -
    
    Returns:
    
    Document - Returns the Document object for the given XML String
    
    Throws:
    
    WidgetDefinitionException
  - updateDOM
```
protected void updateDOM(java.lang.String defXML,
             java.util.Map<java.lang.String,java.util.Map<java.lang.String,org.w3c.dom.Node>> dom)
                  throws WidgetDefinitionException
```
    This method parses the defXML and then updates the passed java object with the result of parsing. This method parses the defXML and looks at child nodes of element. It then retrieves the value of attribute "id", "name", "internalSlotId" in that order for all the childNodes. If any of these attributes are provided, then it saves the node in the dom object sent to this method. The structure of dom object will be Map> dom) ==> Map>
    
    Parameters:
    
    defXML - - XML Definition. Root element should be
    
    dom - - Java object which will contain the result of parsing the defXML
    
    Throws:
    
    WidgetDefinitionException
  - mergeXML
```
public java.lang.String mergeXML(java.lang.String xml1,
                        java.lang.String xml2)
                          throws WidgetDefinitionException
```
    Given 2 XML definitions, this method merges both the XML's and returns the final merged XML. The root element of the XMLs should be The child elements of the root element in xml2 will replace any child elements in xml1 if the elements have same attribute value for attribute: id, name, internalSlotId attributes (in that order, first not-null value will be considered)
    
    Parameters:
    
    xml1 - - First XML
    
    xml2 - - Second XML
    
    Returns:
    
    - Final merged XML
    
    Throws:
    
    WidgetDefinitionException
  - createXML
```
protected java.lang.String createXML(java.util.Map<java.lang.String,java.util.Map<java.lang.String,org.w3c.dom.Node>> dom)
                              throws WidgetDefinitionException
```
    This method creates the XML structure from the passed java object. The structure of dom object will be Map> dom) ==> Map> It loops through the java objects and retrieves all the nodeObject in the Map and appends it to the root element, which will be
    
    Parameters:
    
    dom - - Object containing child nodes.
    
    Returns:
    
    - Definition XML created from dom object
    
    Throws:
    
    WidgetDefinitionException
  - getSlotsDefined
```
public java.util.List<GenericSlotType> getSlotsDefined()
```
    Returns the slots defined in the widget's XML definition. This method must be invoked after the parse method.
    
    Returns:
    
    The list of slot defined in the XML. Null if no slots are defined.
  - getWidgetPropertiesDefined
```
public java.util.List<WidgetPropertyType> getWidgetPropertiesDefined()
```
    Returns the list of widget properties defined for the widget. This method must be invoked after the parse method.
    
    Returns:
    
    The list of widget properties found in the definition XML. Null, if no properties were defined.
  - isMandatoryProperty
```
public java.lang.Boolean isMandatoryProperty(java.lang.String propertyName)
```
    This method indicates if the property specified is required or not. This method must be invoked after the parse method.
    
    Parameters:
    
    propertyName - The name of the widget property.
    
    Returns:
    
    A boolean to indicate if the property is required. Null, if the property name does not exist.
  - getMandatoryWidgetProperties
```
public java.util.Set<java.lang.String> getMandatoryWidgetProperties()
```
    This method returns all the widget property names that are marked mandatory. This method must be invoked after the parse method.
    
    Returns:
    
    A Set of mandatory widget properties for the widget.
  - getDataTypeForProperty
```
public java.lang.String getDataTypeForProperty(java.lang.String propertyName)
```
    This method indicates the data type of the property specified. This method must be invoked after the parse method.
    
    Parameters:
    
    propertyName - The name of the widget property.
    
    Returns:
    
    The data of the property. Null, if the property name does not exist.
  - getWidgetDefinition
```
protected WidgetDefinitionType getWidgetDefinition()
```
    Returns the widget definition object.
    
    Returns:
    
    The widget definition.
  - getPageLayoutFactory
```
protected PageLayoutFactory getPageLayoutFactory()
```
    Returns the instance of PageLayoutFactory to use for constructing SDOs.
    
    Returns:
    
    The PageLayoutFactory instance.
  - addSlot
```
protected void addSlot(GenericSlotType slot)
```
    This method adds a slot instance to the list of slots defined.
    
    Parameters:
    
    slot - The GenericSlotType logical SDO to add.
  - addWidgetProperties
```
protected void addWidgetProperties(java.util.List<WidgetPropertyType> properties)
```
    This method adds to the list of widget properties.
    
    Parameters:
    
    properties - The list of properties to add.
  - createWidgetPropertyFromElement
```
protected java.util.List<WidgetPropertyType> createWidgetPropertyFromElement(org.w3c.dom.Element propertyElement)
```
    This method creates the WidgetProperty from the widget-property element specified. It parses the element to check for the value nodes under it. Based on the number of value nodes, the method returns a list of WidgetProperty objects sequenced in the order of the value nodes. If the value node is not present, the method looks for the value attribute and returns a singleton list with the widget property. If no values are defined, the method returns a singleton list with WidgetProperty populated with just the name.
    
    Parameters:
    
    propertyElement - The element node representing a widget-property.
    
    Returns:
    
    An empty list if the widget property is not well formed. This would happen when the name attribute is null or empty. A list of widget properties otherwise.
  - createSlotFromElement
```
protected GenericSlotType createSlotFromElement(org.w3c.dom.Element slotElement)
```
    This method creates a GenericSlot object from the slot element specified. It looks for the internalSlotId, slotType, x, y, top and left attributes in the element.
    
    Parameters:
    
    slotElement - The node representing the slot element.
    
    Returns:
    
    The GenericSlotType object.
  - createSupportedDeviceClassWidgetProperty
```
protected java.util.List<WidgetPropertyType> createSupportedDeviceClassWidgetProperty(org.w3c.dom.Element supportedDeviceClass)
```
    This method creates the widget properties that indicate the supported device classes for the widget from the supported-device-class element specified. It parses the element to check for the value nodes under it. Based on the number of value nodes, the method returns a list of WidgetProperty objects sequenced in the order of the value nodes. If the value node is not present, the method looks for the value attribute and returns a singleton list with the widget property. The name of the property is _pgl:supportedDeviceClass.
    
    Parameters:
    
    supportedDeviceClass - The element node representing a supported-device-class.
    
    Returns:
    
    A list of widget properties that indicate the supported device classes.

Class WidgetDefinitionParser

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

COPYRIGHT

SLOT_TYPE_ATTRIBUTE

INTERNAL_SLOT_ID_ATTRIBUTE

VALUE_NODE

NAME_ATTRIBUTE

ID_ATTRIBUTE

WIDGET_MANAGER_ELEMENT_NAME

WIDGET_PROPERTY_ELEMENT_NAME

SLOT_ELEMENT_NAME

SUPPORTED_DEVICE_CLASS_ELEMENT_NAME

DEFINITION_ELEMENT_NAME

POSITIONAL_PROPERTY_X

POSITIONAL_PROPERTY_Y

POSITIONAL_PROPERTY_TOP

POSITIONAL_PROPERTY_LEFT

EMPTY_WIDGET_PROPERTY_LIST

Constructor Detail

WidgetDefinitionParser

WidgetDefinitionParser

Method Detail

parse

getDocument

updateDOM

mergeXML

createXML

getSlotsDefined

getWidgetPropertiesDefined

isMandatoryProperty

getMandatoryWidgetProperties

getDataTypeForProperty

getWidgetDefinition

getPageLayoutFactory

addSlot

addWidgetProperties

createWidgetPropertyFromElement

createSlotFromElement

createSupportedDeviceClassWidgetProperty