Difference between revisions of "COSMOS SDD Tooling Examples"

Revision as of 23:48, 5 October 2008

This page contains examples of how to use various functions of the SDD tooling. Please use these examples as references as you create your own applications.

SDD Programmatic Interface

The SPI is used to read and write SDDs with a Java interface. These examples will take the reader through reading, writing, and creating SDDs.

Creating SDDs

The SPI is controlled through one instance of a session. In order to use any methods in the SPI, a session must first be created.

SPISession session = SPISession.DEFAULT_INSTANCE;

The SPI objects for the most part correspond to the SDD types. These objects are created from factory objects, so let's create these first.

BaseFactory baseFactory = session.createBaseFactory();
ContentUnitFactory cuFactory = session.createContentUnitFactory();
ArtifactFactory artifactFactory = session.createArtifactFactory();

Each package of the SPI APIs have a factory class. To create an SPI object, all required elements and attributes of the SPI object must be passed into the factory method. This means we'll be creating our deployment descriptor close to the end. Let's create our install artifact first.

Artifact install = artifactFactory.createInstallArtifact();
install.setContentReference("installArtifact");

This sets up our install artifact and sets the content reference to "installArtifact" which will map to one of the contents in the package descriptor. Next we'll add some additional content:

Collection<AdditionalContent> additionalContents = new ArrayList<AdditionalContent>();
additionalContents.add(artifactFactory.createAdditionalContent("bom"));
AdditionalContent additionalContent = artifactFactory.createAdditionalContent("readme");
additionalContent.setType("readme");
additionalContents.add(additionalContent);
install.setAdditionalContents(additionalContents);

A Collection of AdditionalContent types was created and two AdditionalContent objects were created through the artifact factory. The createAdditionalContent method requires the content reference to be defined, which also must match an entry in the package descriptor. All required elements and attributes of the SDD types will be required for the factory methods as well in order to create that type. The final step was to call the appropriate setter method on the install artifact for the additional content.

Now that we have an artifact, we can create our installable unit. Remember that installable units require artifacts.

InstallableUnit iu = cuFactory.createInstallableUnit("IU_ID", "IU_TARGET_REF", install, ContentUnitFactory.INSTALL_ARTIFACT);

We pass in our newly created install artifact to the factory method to create our install artifact.

One of the last objects we need to create are the resources in the topology.

Collection<Resource> resources = new ArrayList<Resource>();
Resource resource = baseFactory.createResource("OS", "OperatingSystem");
resource.setName("Windows Vista");
resource.setDescription(new TranslatableString("The operationg system of the computer.", "osDesc"));
resource.setShortDescription(new TranslatableString("Computer's OS", "osShortDesc"));
resources.add(resource);

Here we have added one resource to our SDD. The factory method takes the reference ID and then the resource type as parameters. In the two description elements, we've introduced the ability for the SDD to handle translatable strings. The first parameter is the default string. The second parameter is the translation key in the properties file that will accompany the SDD.

Now we'll create our final object:

DeploymentDescriptor dd = baseFactory.createDeploymentDescriptor("1.0", "12341234123412341234123412341234".getBytes(), Calendar.getInstance().getTime(), iu, resources);

We have everything we need and we finally create the deployment descriptor object. We pass in the schema version (usually 1.0), the descriptor UUID, last modified time, our installable unit, and our resources. Similar techniques can be used to create the package descriptor and add additional elements to the SDD.

Reading SDDs

Using DOM

For reading an SDD, we first need a DOM document. There's a few things I like to setup before reading the actual file into memory.

DocumentBuilderFactory docBuilderFactory = DocumentBuilderFactory.newInstance();
docBuilderFactory.setValidating(false);
docBuilderFactory.setNamespaceAware(true);

DocumentBuilder docBuilder = docBuilderFactory.newDocumentBuilder();
docBuilder.setErrorHandler(new ErrorHandler()
{
    public void warning(SAXParseException e) throws SAXException {
        printErrorMessage(e);
    }

    public void error(SAXParseException e) throws SAXException {
        printErrorMessage(e);
    }

    public void fatalError(SAXParseException e) throws SAXException {
        printErrorMessage(e);
    }
            
    private void printErrorMessage(SAXParseException e)
    {
        System.out.println("Line: " + e.getLineNumber() + ": " + e.getMessage());
    }
});

With that all set, we'll create the Document object.

Document doc = docBuilder.parse(new InputSource("mySDD.xml"));</code>

SPISession session = SPISession.DEFAULT_INSTANCE;
DeploymentDescriptor dd = (DeploymentDescriptor) session.buildDescriptorFromDocument(doc);

At this point, you can run through all the getter methods to get at the data you need to read.

Using the Validator

The validator has methods to read files from the disk to provide you with a Document object.

SDD_DAS sddDas = new SDD_DASImpl();
Document doc = sddDas.loadDocument(new FileInputStream("mySDD.xml"));
SPISession session = SPISession.DEFAULT_INSTANCE;
DeploymentDescriptor dd = (DeploymentDescriptor) session.buildDescriptorFromDocument(doc);

Writing SDDs

Using DOM

Once you've either created an SDD or read one in to change some values, you probably want to write it back to the system. Let's setup some DOM objects first.

DOMImplementationRegistry domRegistry = DOMImplementationRegistry.newInstance();
DOMImplementationLS domImpl = (DOMImplementationLS) domRegistry.getDOMImplementation("LS");
LSSerializer serializer = domImpl.createLSSerializer();
serializer.getDomConfig().setParameter("format-pretty-print", true);

This will format our xml like we're used to seeing. Otherwise you may see everything on one line. Now we write it to a file.

Document doc = dd.getOwnerDocument();
FileWriter fw = new FileWriter("mySDD.xml");
BufferedWriter bw = new BufferedWriter(fw);

bw.write(lsSerializer.writeToString(doc));
bw.close();

The dd object here is our deployment descriptor.

Using the Validator

The SDD Validator has methods to write documents to the disk. It also validates the SDDs, which will be seen in the next section. This will write the SDD to the file mySDD.xml. The null parameter corresponds to the encoding, which defaults to UTF-8. The false parameter tells the validator to save the SDD without validating.

SDD_DAS deploymentDescriptorDAS = new SDD_DASImpl();
deploymentDescriptorDAS.saveDocument(document, new FileOutputStream("mySDD.xml"), null, false);

Validator

The validator is used to verify the SDD follows the constraints of the schema. It also allows you to specify your own rules to constrain the SDD. First, we'll look at the easiest way to validate the SDD against the schema.

SDD_DAS deploymentDescriptorDAS = new SDD_DASImpl();
Collection<XMLValidationError> validationErrors = deploymentDescriptorDAS.validate(document);
if (validationErrors.size() > 0) 
{
	for (XMLValidationError error : validationErrors) {
		System.err.println(error.getErrorMessage());
	}
}

If a custom rule is desired, we'll need to create a rule that the validator can understand.