Programmer's Guide



Chapter 5   Using XML in SilverStream

The XML language (eXtensible Markup Language) allows you to create XML documents that can be used to exchange data between computer systems (of different types) and applications on the web. This chapter describes SilverStream use of and support for XML documents. It covers the following topics:

SilverStream XML support   Top of page

SilverStream uses XML documents for the following:

SilverStream automatically installs the IBM XML for Java parser (XML4J) into the SilverStream lib subdirectory. XML4J supports XML's core features which you use within your SilverStream applications.

NOTE   SilverStream explicitly supports XML for EJB deployment descriptors and for SilverCmd input files. If you use the other features of XML4J, be aware that SilverStream support can change over time. You can only use XML4J for server-side applications. The XML library is not available to the SilverStream client-side runtime environment.

    For more information on XML4J's features and API, see the IBM XML4J online help (provided with SilverStream) or IBM's Web site at http://www.alphaworks.ibm.com/tech/xml4j.

Also, if you had explicitly been using XML4J in an application using SilverStream 3.0, see XML Parser for Java for information on updating to the new version of XML4J provided with this release of SilverStream.

Using XML with EJBs   Top of page

The EJB 1.1 specification requires that deployment descriptors be in XML format. SilverStream's EJB implementation complies with this requirement.

When you build your EJB applications using the SilverStream IDE, you can use the Descriptor tab of the JAR Designer to construct your deployment descriptor. The JAR Designer provides a List Mode (GUI) and a Text Mode (raw XML).

When you build your EJB applications in another IDE and deploy the EJB on SilverStream, you can use the JAR Designer Descriptor tab to modify the deployment descriptor after you have imported the EJB JAR to SilverStream.

    For more information about using the JAR Designer for deployment descriptors, see the JAR Designer chapter in the online Tools Guide.

Using XML with SilverCmd   Top of page

SilverCmd is a command-line interface that allows you to automate many basic SilverStream tasks. It includes commands that let you import or export server-side objects, add or delete databases, and so on.

Many of the commands allow (while some require) you to provide additional information in an input file, and the input file must be an XML document.

SilverStream provides a predefined set of DTDs for each input file. A DTD (document type definition) defines the rules for an XML document. For example, it specifies which tags can be used in an XML document, which elements are required, which elements are optional, and so on. Each DTD includes comments that provide documentation about the input file format. The comments in the DTD provide the most up-to-date documentation for any SilverStream release.

SilverStream also supplies sample input files that illustrate correctly formatted input files.

Working with the SilverCmd input files

If you are an XML expert, you can:

  1. Examine the DTD for your input file type. (These are cross-referenced in the SilverCmd reference chapter in the online Tools Guide.)

  2. Write your own XML document that complies with the specified DTD.

If you are new to XML, you should:

  1. Find the appropriate sample file in the DTDs subdirectory.

  2. Copy and rename the file, and place it in an appropriate working location.

  3. Update the contents of each tag to reflect your own requirements. (You can use any text editor.)

  4. Test the changes you've made to the file, to make sure they perform as you expect.

Understanding the sample files

If you are new to XML, it might be helpful to try and understand one of the sample files before you get started. The input file required for SilverCmd's Delete operation is relatively simple, so it is a good place to begin.

You can use the Delete command to delete a SilverStream form, page, business object, or media item from the server. If you only want to delete a single item, then you can specify that item directly on the command line; however, if you want to delete multiple objects in a single operation, then you must specify the items to delete in an input file. The example, delete_sample.xml, resides in the DTDs subdirectory of the SilverStream installation directory. It looks like this:

  <?xml version="1.0" encoding="UTF-8"?> 
<?AgMetaXML 1.0?>
<!-- Uses DTD "itemlist.dtd" -->
<obj_ItemList>
   <Items type = "StringArray">
      <el>Forms/test1</el> <!-- The form "test1"-->
      <el>Objects/com/myco/pkg1/MyObject</el> <!-- The object
             "com.myco.pkg1.MyObject" -->
   </Items>
</obj_ItemList>

Here are a few things to note about this sample:

Updating the delete_sample.xml file

To modify the delete_sample.xml file for your own use, you can change the text enclosed by the <el> tags to the names of the items that you want to delete. You need to specify the appropriate SilverStream server directory structure for the type of items that you want to delete. For more information, see the SilverCmd reference chapter in the online Tools Guide.

Understanding the ItemList.dtd

Let's briefly look at the itemlist.dtd which defines how the delete_sample.xml file should be structured. The itemlist.dtd file is also located in the DTDs subdirectory.

  <!-- ItemList MetaXML DTD --> 
<!-- ItemList contains only one property, a StringArray named "Items". The items in this array identify items on the server. Each item can be in one of the following three forms:
<dir>/myitem where <dir> is one of: Forms, Views, Pages
Objects/mypkg/myitem for Business Objects
Media/<dir>/myitem where <dir> is one of: Jars, Images, Sounds, General
For some commands, the name of the item itself ("myitem") can be left off to specify a package or directory.-->

<!ELEMENT obj_ItemList (Items)>

<!ELEMENT Items (el*)>
<!ATTLIST Items type (StringArray) "StringArray">

<!ELEMENT el (#PCDATA)>
--------------------------------------

Here are a few things to note about this DTD.

You can learn more about DTDs and their structure from one of the resources listed in the Resources for learning about XML section of this chapter.

Resources for learning about XML    Top of page

If you're new to XML or just need to explore a specific XML topic, try the following recommended learning resource:

Resource

Description

SilverStream DevCenter

An index to XML learning and reference materials with links to many documents and Web sites

    Available at the SilverStream DevCenter Web site: http://devcenter.silverstream.com/






Copyright © 2000, SilverStream Software, Inc. All rights reserved.