Package com.smartgwt.client.data

# Class XMLTools

java.lang.Object
com.smartgwt.client.data.XMLTools

public class XMLTools extends Object
Utility methods for dealing with XML elements, XML Schema, WSDL files, XSLT, and other XML-related functionality.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `XMLTools()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `disableIEXMLHackaround()`
  Disables an Internet Explorer-specific work around for the MSXML bug that the 'xml' namespace prefix cannot be explicitly declared.
  `static void`
  `loadWSDL(String wsdlURL, WSDLLoadCallback callback)`
  Load a WSDL file and create an instance of WebService that allows invoking operations and binding DataSources to web service operations.
  `static void`
  `loadWSDL(String wsdlURL, WSDLLoadCallback callback, RPCRequest requestProperties)`
  Load a WSDL file and create an instance of WebService that allows invoking operations and binding DataSources to web service operations.
  `static void`
  `loadWSDL(String wsdlURL, WSDLLoadCallback callback, RPCRequest requestProperties, boolean autoLoadImports)`
  Load a WSDL file and create an instance of WebService that allows invoking operations and binding DataSources to web service operations.
  `static void`
  `loadXMLSchema(String schemaURL, XSDLoadCallback callback)`
  Load an XML file containing XML schema definitions and create DataSource and SimpleType objects to represent the schema.
  `static void`
  `loadXMLSchema(String schemaURL, XSDLoadCallback callback, RPCRequest requestProperties)`
  Load an XML file containing XML schema definitions and create DataSource and SimpleType objects to represent the schema.
  `static void`
  `loadXMLSchema(String schemaURL, XSDLoadCallback callback, RPCRequest requestProperties, boolean autoLoadImports)`
  Load an XML file containing XML schema definitions and create DataSource and SimpleType objects to represent the schema.
  `static boolean`
  `nativeXMLAvailable()`
  Returns true if the current browser exposes an XML parser that can be used for Smart GWT XML operations like web service bindings and XML processing.
  `static Object`
  `selectNodes(Object element, String expression)`
  Retrieve a set of nodes from an XML element or document based on an XPath expression.
  `static Object`
  `selectNodes(Object element, String expression, Map namespaces)`
  Retrieve a set of nodes from an XML element or document based on an XPath expression.
  `static int`
  `selectNumber(Object element, String expression)`
  Retrieve a numeric value from an XML element or document based on an XPath expression.
  `static int`
  `selectNumber(Object element, String expression, Map namespaces)`
  Retrieve a numeric value from an XML element or document based on an XPath expression.
  `static JSONArray`
  `selectObjects(Object element, String expression)`
  Applies an XPath expression to JavaScript objects, returning matching objects.
  `static String`
  `selectString(Object element, String expression)`
  Retrieve a string value from an XML element or document based on an XPath expression.
  `static String`
  `selectString(Object element, String expression, Map namespaces)`
  Retrieve a string value from an XML element or document based on an XPath expression.
  `static JavaScriptObject`
  `toJS(Object elements)`
  Translates an XML fragment to JavaScript collections.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### XMLTools

    public XMLTools()

- ## Method Details

  - ### disableIEXMLHackaround

    public static void disableIEXMLHackaround()
    Disables an Internet Explorer-specific work around for the MSXML bug that the 'xml' namespace prefix cannot be explicitly declared.

    Though redundant, the Namespaces in XML spec allows XML documents to explicitly declare namespace prefix 'xml' bound to namespace name `http://www.w3.org/XML/1998/namespace`; e.g.

        xmlns:xml="http://www.w3.org/XML/1998/namespace"

    MSXML does not allow the 'xml' namespace prefix to be declared, and will raise the XML parse error: The namespace prefix is not allowed to start with the reserved string "xml". Microsoft has disclosed this bug as a Normative Variation in MSXML: http://msdn.microsoft.com/en-us/library/ff460535(v=vs.85).aspx. A framework-level work around is used by default in `parseXML()` where if the string `xmlns:xml="http://www.w3.org/XML/1998/namespace"` or `xmlns:xml='http://www.w3.org/XML/1998/namespace'` is found in the first 1000 characters of the `xmlText` parameter to parseXML(), then these two strings are removed from `xmlText` wherever they appear. This work around may be disabled by calling disableIEXMLHackaround() at any time before parseXML() is called.

  - ### nativeXMLAvailable

    public static boolean nativeXMLAvailable()
    Returns true if the current browser exposes an XML parser that can be used for Smart GWT XML operations like web service bindings and XML processing. See `PlatformDependencies` for more information on when the XML parser may not available and what features are impacted as a result.
    Returns:
      true if native XML processing is available, false otherwise.

  - ### loadXMLSchema

    public static void loadXMLSchema(String schemaURL, XSDLoadCallback callback)
    Load an XML file containing XML schema definitions and create DataSource and SimpleType objects to represent the schema. You can use to loaded schema to bind ISC components, perform validation, create editing interfaces, and build other metadata-driven interfaces.

    All <xsd:complexType> declarations become ISC DataSources, and all <xsd:simpleType> definitions become atomic type definitions.

    By default, named complexType definitions and named element definitions containing complexTypes become global DataSources, that is, they can be fetched with DataSource.getDataSource(). Inline complexType definitions get automatically generated names.

    Named simpleType declarations become global ISC atomic types, that is, subsequently defined DataSources can use them for DataSourceField.type. XML schema "restrictions" for simple types are automatically translated to DataSourceField.valueMap or DataSourceField.validators as appropriate.

    The created SchemaSet object is available in the callback as the single parameter "schemaSet", or can retrieved via SchemaSet.get(schemaNamespace).

    NOTE: required fields: the XML concept of "required" for an attribute or subelement, expressed via use="required" (for an attribute) or minOccurs > 0 (for a subelement), is that the attribute or element must be present in the XML document but can have any value, including being empty or null. The SmartGWT notion of required means non-null. You can express the SmartClient notion of required in XML Schema with the combination of maxOccurs>0 and a minLength or length "restriction", and SmartClient will recognize the field as SmartClient-required, with all of the behaviors that implies (eg, specially styled form titles, automatic validation, etc).

    Parameters:
      `schemaURL` - URL to load the schema from
      `callback` - the callback

  - ### loadXMLSchema

    public static void loadXMLSchema(String schemaURL, XSDLoadCallback callback, RPCRequest requestProperties)
    Load an XML file containing XML schema definitions and create DataSource and SimpleType objects to represent the schema. You can use to loaded schema to bind ISC components, perform validation, create editing interfaces, and build other metadata-driven interfaces.

    All <xsd:complexType> declarations become ISC DataSources, and all <xsd:simpleType> definitions become atomic type definitions.

    By default, named complexType definitions and named element definitions containing complexTypes become global DataSources, that is, they can be fetched with DataSource.getDataSource(). Inline complexType definitions get automatically generated names.

    Named simpleType declarations become global ISC atomic types, that is, subsequently defined DataSources can use them for DataSourceField.type. XML schema "restrictions" for simple types are automatically translated to DataSourceField.valueMap or DataSourceField.validators as appropriate.

    The created SchemaSet object is available in the callback as the single parameter "schemaSet", or can retrieved via SchemaSet.get(schemaNamespace).

    NOTE: required fields: the XML concept of "required" for an attribute or subelement, expressed via use="required" (for an attribute) or minOccurs > 0 (for a subelement), is that the attribute or element must be present in the XML document but can have any value, including being empty or null. The SmartGWT notion of required means non-null. You can express the SmartClient notion of required in XML Schema with the combination of maxOccurs>0 and a minLength or length "restriction", and SmartClient will recognize the field as SmartClient-required, with all of the behaviors that implies (eg, specially styled form titles, automatic validation, etc).

    Parameters:
      `schemaURL` - URL to load the schema from
      `callback` - the callback
      `requestProperties` - additional properties to set on the RPCRequest that will be issued

  - ### loadXMLSchema

    public static void loadXMLSchema(String schemaURL, XSDLoadCallback callback, RPCRequest requestProperties, boolean autoLoadImports)
    Load an XML file containing XML schema definitions and create DataSource and SimpleType objects to represent the schema. You can use to loaded schema to bind ISC components, perform validation, create editing interfaces, and build other metadata-driven interfaces.

    All <xsd:complexType> declarations become ISC DataSources, and all <xsd:simpleType> definitions become atomic type definitions.

    By default, named complexType definitions and named element definitions containing complexTypes become global DataSources, that is, they can be fetched with DataSource.getDataSource(). Inline complexType definitions get automatically generated names.

    Named simpleType declarations become global ISC atomic types, that is, subsequently defined DataSources can use them for DataSourceField.type. XML schema "restrictions" for simple types are automatically translated to DataSourceField.valueMap or DataSourceField.validators as appropriate.

    The created SchemaSet object is available in the callback as the single parameter "schemaSet", or can retrieved via SchemaSet.get(schemaNamespace).

    NOTE: required fields: the XML concept of "required" for an attribute or subelement, expressed via use="required" (for an attribute) or minOccurs > 0 (for a subelement), is that the attribute or element must be present in the XML document but can have any value, including being empty or null. The SmartGWT notion of required means non-null. You can express the SmartClient notion of required in XML Schema with the combination of maxOccurs>0 and a minLength or length "restriction", and SmartClient will recognize the field as SmartClient-required, with all of the behaviors that implies (eg, specially styled form titles, automatic validation, etc).

    Parameters:
      `schemaURL` - URL to load the schema from
      `callback` - the callback
      `requestProperties` - additional properties to set on the RPCRequest that will be issued
      `autoLoadImports` - if set, xsd: The callback will not fire until all dependencies have been loaded

  - ### loadWSDL

    public static void loadWSDL(String wsdlURL, WSDLLoadCallback callback)
    Load a WSDL file and create an instance of WebService that allows invoking operations and binding DataSources to web service operations. The created WebService object is available in the callback as the single parameter "service", or can retrieved via WebService.get(serviceNamespace).

    XML Schema present in the WSDL file will also will also be processed as described in XMLTools.loadXMLSchema().

    Platform notes: loadWSDL() is not supported in Safari 2.0 (but is supported in Safari 3.0.3 and greater)

    Parameters:
      `wsdlURL` - URL to load the WSDL file from
      `callback` - the callback

  - ### loadWSDL

    public static void loadWSDL(String wsdlURL, WSDLLoadCallback callback, RPCRequest requestProperties)
    Load a WSDL file and create an instance of WebService that allows invoking operations and binding DataSources to web service operations. The created WebService object is available in the callback as the single parameter "service", or can retrieved via WebService.get(serviceNamespace).

    XML Schema present in the WSDL file will also will also be processed as described in XMLTools.loadXMLSchema().

    Platform notes: loadWSDL() is not supported in Safari 2.0 (but is supported in Safari 3.0.3 and greater)

    Parameters:
      `wsdlURL` - URL to load the WSDL file from
      `callback` - the callback
      `requestProperties` - additional properties to set on the RPCRequest that will be issued

  - ### loadWSDL

    public static void loadWSDL(String wsdlURL, WSDLLoadCallback callback, RPCRequest requestProperties, boolean autoLoadImports)
    Load a WSDL file and create an instance of WebService that allows invoking operations and binding DataSources to web service operations. The created WebService object is available in the callback as the single parameter "service", or can retrieved via WebService.get(serviceNamespace).

    XML Schema present in the WSDL file will also will also be processed as described in XMLTools.loadXMLSchema().

    Platform notes: loadWSDL() is not supported in Safari 2.0 (but is supported in Safari 3.0.3 and greater)

    Parameters:
      `wsdlURL` - URL to load the WSDL file from
      `callback` - the callback
      `requestProperties` - additional properties to set on the RPCRequest that will be issued
      `autoLoadImports` - if set, xsd: The callback will not fire until all dependencies have been loaded

  - ### selectString

    public static String selectString(Object element, String expression)
    Retrieve a string value from an XML element or document based on an XPath expression. If more than one node matches, only the first node's value will be returned.

    Namespacing works as described under XMLTools.selectNodes()

    NOTE: this API cannot be supported on the Safari web browser for versions prior to 3.0.3.

    Parameters:
      `element` - Native XMLElement, document or String xml to select from
      `expression` - XPath expression to use to select nodes
    Returns:
      result of the XPath, in String form

  - ### selectString

    public static String selectString(Object element, String expression, Map namespaces)
    Retrieve a string value from an XML element or document based on an XPath expression. If more than one node matches, only the first node's value will be returned.

    Namespacing works as described under XMLTools.selectNodes()

    NOTE: this API cannot be supported on the Safari web browser for versions prior to 3.0.3.

    Parameters:
      `element` - Native XMLElement, document or String xml to select from
      `expression` - XPath expression to use to select nodes
      `namespaces` - namespaces
    Returns:
      result of the XPath, in String form

  - ### selectNodes

    public static Object selectNodes(Object element, String expression)
    Retrieve a set of nodes from an XML element or document based on an XPath expression.
    Parameters:
      `element` - Native XMLElement,document or string xml to select from
      `expression` - XPath expression to use to select nodes
    Returns:
      list of nodes matching XPath

  - ### selectNodes

    public static Object selectNodes(Object element, String expression, Map namespaces)
    Retrieve a set of nodes from an XML element or document based on an XPath expression.

    If the target document is namespaced, namespace prefixes declared in the document element of the target document will be available, as well as the default namespace, if declared, under the prefix "default".

    To declare your own namespace prefixes, provide a prefix to URI mapping as a simple JS Object, for example:

         {
          az : "http://webservices.amazon.com/AWSECommerceService/2005-03-23",
          xsd : "http://www.w3.org/2001/XMLSchema"
         }

    NOTE: this API cannot be supported on the Safari web browser for versions earlier than 3.0.3.
    Parameters:
      `element` - Native XMLElement,document to select from
      `expression` - XPath expression to use to select nodes
      `namespaces` - namespace mapping used by the expression as prefix -> URI mapping
    Returns:
      list of nodes matching XPath

  - ### selectObjects

    public static JSONArray selectObjects(Object element, String expression)
    Applies an XPath expression to JavaScript objects, returning matching objects.
    Parameters:
      `element` - Object to select results from
      `expression` - XPath expression
    Returns:
      Array of matching objects, or null for no match

  - ### toJS

    public static JavaScriptObject toJS(Object elements)
    Translates an XML fragment to JavaScript collections.
    Parameters:
      `elements` - XMLElement or XMLDocument element to transform to JS
    Returns:
      The resulting JavaScript collection

  - ### selectNumber

    public static int selectNumber(Object element, String expression)
    Retrieve a numeric value from an XML element or document based on an XPath expression.

    If more than one node matches, only the first node's value will be returned.

    Namespacing works as described under +link{XMLTools.selectNodes()}

    NOTE: this API cannot be supported on the Safari web browser for versions prior to 3.0.3.

    Parameters:
      `element` - Native XMLElement, document or String xml to select from
      `expression` - XPath expression to use to select nodes
    Returns:
      result of the XPath, in int form

  - ### selectNumber

    public static int selectNumber(Object element, String expression, Map namespaces)
    Retrieve a numeric value from an XML element or document based on an XPath expression.

    If more than one node matches, only the first node's value will be returned.

    Namespacing works as described under +link{XMLTools.selectNodes()}

    NOTE: this API cannot be supported on the Safari web browser for versions prior to 3.0.3.

    Parameters:
      `element` - Native XMLElement, document or String xml to select from
      `expression` - XPath expression to use to select nodes
      `namespaces` - namespaces
    Returns:
      result of the XPath, in int form