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 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.
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.
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.
If you are an XML expert, you can:
If you are new to XML, you should:
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:
NOTE These first two lines are not required. However, they are useful for documentation.
<!DOCTYPE obj_Itemlist SYSTEM "itemlist.dtd">
If the DTD is in the same directory as the XML document you can just specify the file name. If it is located in a different directory, then you must use a fully qualified file name.
<obj_ItemList>
<Items>
<el>
<el>
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.
An element declaration provides two things. First, it specifies the name of the element. This name is used in the XML document as a tag. Second, it defines the kind of data that the element can contain. This is sometimes called the content model. In our example, the element declaration:
<!ELEMENT obj_ItemList (Items)>
means that the XML document will contain a tag named <obj_ItemList>, and that the <obj_ItemList> tag can contain an <Items> tag. The DTD must then define the <Items> tag.
<!ELEMENT Items (el*)>
specifies that the XML file contains an <Items> tag, and that <Items> can contain zero or more <el> tags.
The asterisk (*) indicates zero or more. Some additional symbols include:
<!ATTLIST Items type (StringArray) "StringArray">
uses the ATTLIST keyword which is used to describe the set of attributes that can be applied to instances of Items. For this example, Items can have a "type" attribute which can only be a StringArray. This kind of construct is used repeatedly in SilverStream DTDs to indicate to SilverStream the type of input data.
<!ELEMENT el (#PCDATA)>
describes the <el> tag and its content model as PCDATA. PCDATA is another keyword that means an <el> tag can only contain character data.
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.
If you're new to XML or just need to explore a specific XML topic, try the following recommended learning resource:
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/ |