[cosmos-dev] How the SPI retrieves data from the DOM tree

["Chris Mildebrandt" <cosmos@xxxxxxxxxxxxxxxx>]

Mark,

This is regarding the question you had during the Tuesday ME meeting. The SPI saves the SDD in a DOM object and uses that as the data model. The SPI classes are used as a convenience to developers to get data in a manner that reflects the SDD structure. When an SDD is read into the SPI, the user gets a DeploymentDescriptor object. From here, the user will drill down through the getters to obtain the required object. For instance, here's the getter for resources from DeploymentDescriptor:

    public Collection<Resource> getResources() {
        Collection<Resource> resources = new ArrayList<Resource>();

        if (isSetElement("Topology")) {
            Element topology = getChild("Topology");
            Collection<Element> tmpList = session.getChildren(topology, "Resource");

            for (Element element : tmpList)
            {
                resources.add(new ResourceImpl(element, session));
            }
        }
       
        return resources;
    }

A collection of Resource classes is created. Then a getChild() method is called to obtain the DOM Element that represents topology. Next, all the first level resource elements in topology are returned as a collection of Elements. The session.getChildren() method does this by taking the parent element (topology) and returning all the elements with the node name of "Resource" using DOM calls. You can see this code in the SPISessionImpl class. For each of the returned elements, a new Resource class instance is created. The only thing the constructor does is to save the resource element and the session objects. The collection of these resources is returned.

As you can see here, there is no Topology class. The only job of topology is to hold resources. So we decided to let the user obtain the resources directly from the depolyment descriptor. You'll see this in a few other places as well.

There isn't a way to go directly from the DeploymentDescriptor object to a specfic piece of data. If people are familiar with xpath, they can use the internal methods to get access to the DOM objects directly. We don't really approve of that method, which is why it's internal. But since there is no data stored outside of the DOM tree, there should be no problem in modifying it directly.

One thing to note, the SPI deals with copies of objects, not references. If you create a resource, and then save it into the tree, you can change that resource and not affect the tree's copy. Same with retrieving data. If you get a resource from the tree and change it, you must go back and save your changes through the setter interface.

Let me know if you have any additional questions,
-Chris