org.fourthline.cling.support.contentdirectory

## Class DIDLParser

- java.lang.Object
- - org.seamless.xml.SAXParser
  - - org.fourthline.cling.support.contentdirectory.DIDLParser

-     public class DIDLParser
      extends org.seamless.xml.SAXParser

  DIDL parser based on SAX for reading and DOM for writing.

  This parser requires Android platform level 8 (2.2).

  Override the `createDescMetaHandler(org.fourthline.cling.support.model.DescMeta, org.seamless.xml.SAXParser.Handler)` method to read vendor extension content of `<desc>` elements. You then should also override the `populateDescMetadata(org.w3c.dom.Element, org.fourthline.cling.support.model.DescMeta)` method for writing.

  Override the `createItemHandler(org.fourthline.cling.support.model.item.Item, org.seamless.xml.SAXParser.Handler)` etc. methods to register custom handlers for vendor-specific elements and attributes within items, containers, and so on.

  Author:
    Christian Bauer, Mario Franco

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `DIDLParser.ContainerHandler`
    `class` | `DIDLParser.DescMetaHandler` Extracts an `org.w3c.Document` from the nested elements in the `<desc>` element.
    `class` | `DIDLParser.DIDLObjectHandler<I extends DIDLObject>`
    `class` | `DIDLParser.ItemHandler`
    `protected class` | `DIDLParser.ResHandler`
    `class` | `DIDLParser.RootHandler`

    - ### Nested classes/interfaces inherited from class org.seamless.xml.SAXParser

      `org.seamless.xml.SAXParser.Handler<I>, org.seamless.xml.SAXParser.SimpleErrorHandler`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `UNKNOWN_TITLE`

    - ### Fields inherited from class org.seamless.xml.SAXParser

      `XML_SCHEMA_NAMESPACE, XML_SCHEMA_RESOURCE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DIDLParser()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `appendClass(Document descriptor, Element parent, DIDLObject.Class clazz, String element, boolean appendDerivation)`
    `protected void` | `appendProperties(Document descriptor, Element parent, DIDLObject object, String prefix, Class<? extends DIDLObject.Property.NAMESPACE> namespace, String namespaceURI)`
    `protected String` | `booleanToInt(boolean b)`
    `protected Document` | `buildDOM(DIDLContent content, boolean nestedItems)`
    `protected Container` | `createContainer(Attributes attributes)`
    `protected DIDLParser.ContainerHandler` | `createContainerHandler(Container instance, org.seamless.xml.SAXParser.Handler parent)`
    `protected DescMeta` | `createDescMeta(Attributes attributes)`
    `protected DIDLParser.DescMetaHandler` | `createDescMetaHandler(DescMeta instance, org.seamless.xml.SAXParser.Handler parent)`
    `protected Item` | `createItem(Attributes attributes)`
    `protected DIDLParser.ItemHandler` | `createItemHandler(Item instance, org.seamless.xml.SAXParser.Handler parent)`
    `protected DIDLParser.ResHandler` | `createResHandler(Res instance, org.seamless.xml.SAXParser.Handler parent)`
    `protected Res` | `createResource(Attributes attributes)`
    `protected DIDLParser.RootHandler` | `createRootHandler(DIDLContent instance, org.seamless.xml.SAXParser parser)`
    `void` | `debugXML(String s)` Sends the given string to the log with `Level.FINE`, if that log level is enabled.
    `protected String` | `documentToString(Document document, boolean omitProlog)`
    `String` | `generate(DIDLContent content)` Generates a XML representation of the content model.
    `String` | `generate(DIDLContent content, boolean nestedItems)` Generates an XML representation of the content model.
    `protected void` | `generateContainer(Container container, Document descriptor, Element parent, boolean nestedItems)`
    `protected void` | `generateDescMetadata(DescMeta descMeta, Document descriptor, Element parent)`
    `protected void` | `generateItem(Item item, Document descriptor, Element parent)`
    `protected void` | `generateResource(Res resource, Document descriptor, Element parent)`
    `protected void` | `generateRoot(DIDLContent content, Document descriptor, boolean nestedItems)`
    `DIDLContent` | `parse(String xml)` Reads and unmarshalls an XML representation into a DIDL content model.
    `DIDLContent` | `parseResource(String resource)` Uses the current thread's context classloader to read and unmarshall the given resource.
    `protected void` | `populateDescMetadata(Element descElement, DescMeta descMeta)` Expects an `org.w3c.Document` as metadata, copies nodes of the document into the DIDL content.

    - ### Methods inherited from class org.seamless.xml.SAXParser

      `create, createSchema, getErrorHandler, getSchemaSources, parse, setContentHandler`

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

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

- - ### Field Detail

    - #### UNKNOWN_TITLE

          public static final String UNKNOWN_TITLE

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DIDLParser

          public DIDLParser()

  - ### Method Detail

    - #### parseResource

          public DIDLContent parseResource(String resource)
                                    throws Exception

      Uses the current thread's context classloader to read and unmarshall the given resource.
      Parameters:
        `resource` - The resource on the classpath.
      Returns:
        The unmarshalled DIDL content model.
      Throws:
        `Exception`

    - #### parse

          public DIDLContent parse(String xml)
                            throws Exception

      Reads and unmarshalls an XML representation into a DIDL content model.
      Parameters:
        `xml` - The XML representation.
      Returns:
        A DIDL content model.
      Throws:
        `Exception`

    - #### createRootHandler

          protected DIDLParser.RootHandler createRootHandler(DIDLContent instance,
                                                             org.seamless.xml.SAXParser parser)

    - #### createContainerHandler

          protected DIDLParser.ContainerHandler createContainerHandler(Container instance,
                                                                       org.seamless.xml.SAXParser.Handler parent)

    - #### createItemHandler

          protected DIDLParser.ItemHandler createItemHandler(Item instance,
                                                             org.seamless.xml.SAXParser.Handler parent)

    - #### createResHandler

          protected DIDLParser.ResHandler createResHandler(Res instance,
                                                           org.seamless.xml.SAXParser.Handler parent)

    - #### createDescMetaHandler

          protected DIDLParser.DescMetaHandler createDescMetaHandler(DescMeta instance,
                                                                     org.seamless.xml.SAXParser.Handler parent)

    - #### createContainer

          protected Container createContainer(Attributes attributes)

    - #### createItem

          protected Item createItem(Attributes attributes)

    - #### createResource

          protected Res createResource(Attributes attributes)

    - #### createDescMeta

          protected DescMeta createDescMeta(Attributes attributes)

    - #### generate

          public String generate(DIDLContent content)
                          throws Exception

      Generates a XML representation of the content model.

      Items inside a container will not be represented in the XML, the containers will be rendered flat without children.

      Parameters:
        `content` - The content model.
      Returns:
        An XML representation.
      Throws:
        `Exception`

    - #### generate

          public String generate(DIDLContent content,
                                 boolean nestedItems)
                          throws Exception

      Generates an XML representation of the content model.

      Optionally, items inside a container will be represented in the XML, the container elements then have nested item elements. Although this parser can read such a structure, it is unclear whether other DIDL parsers should and actually do support this XML.

      Parameters:
        `content` - The content model.
        `nestedItems` - `true` if nested item elements should be rendered for containers.
      Returns:
        An XML representation.
      Throws:
        `Exception`

    - #### documentToString

          protected String documentToString(Document document,
                                            boolean omitProlog)
                                     throws Exception

      Throws:
        `Exception`

    - #### buildDOM

          protected Document buildDOM(DIDLContent content,
                                      boolean nestedItems)
                               throws Exception

      Throws:
        `Exception`

    - #### generateRoot

          protected void generateRoot(DIDLContent content,
                                      Document descriptor,
                                      boolean nestedItems)

    - #### generateContainer

          protected void generateContainer(Container container,
                                           Document descriptor,
                                           Element parent,
                                           boolean nestedItems)

    - #### generateItem

          protected void generateItem(Item item,
                                      Document descriptor,
                                      Element parent)

    - #### generateResource

          protected void generateResource(Res resource,
                                          Document descriptor,
                                          Element parent)

    - #### generateDescMetadata

          protected void generateDescMetadata(DescMeta descMeta,
                                              Document descriptor,
                                              Element parent)

    - #### populateDescMetadata

          protected void populateDescMetadata(Element descElement,
                                              DescMeta descMeta)

      Expects an `org.w3c.Document` as metadata, copies nodes of the document into the DIDL content.

      This method will ignore the content and log a warning if it's of the wrong type. If you override `createDescMetaHandler(org.fourthline.cling.support.model.DescMeta, org.seamless.xml.SAXParser.Handler)`, you most likely also want to override this method.

      Parameters:
        `descElement` - The DIDL content `<desc>` element wrapping the final metadata.
        `descMeta` - The metadata with a `org.w3c.Document` payload.

    - #### appendProperties

          protected void appendProperties(Document descriptor,
                                          Element parent,
                                          DIDLObject object,
                                          String prefix,
                                          Class<? extends DIDLObject.Property.NAMESPACE> namespace,
                                          String namespaceURI)

    - #### appendClass

          protected void appendClass(Document descriptor,
                                     Element parent,
                                     DIDLObject.Class clazz,
                                     String element,
                                     boolean appendDerivation)

    - #### booleanToInt

          protected String booleanToInt(boolean b)

    - #### debugXML

          public void debugXML(String s)

      Sends the given string to the log with `Level.FINE`, if that log level is enabled.
      Parameters:
        `s` - The string to send to the log.

Copyright © 2016 4th Line GmbH, Switzerland. All rights reserved.