10
XML and the Oracle Internet File System

XML is used extensively with Oracle 9iFS, both as a method of data transfer and as a mechanism for system configuration. This chapter describes some of the specific supports built into Oracle 9iFS for working with XML data.

This chapter covers the following topics:

• Understanding XML

• Using XML Data Files with Oracle 9iFS

• Configuring Oracle 9iFS Using XML Files

Understanding XML

XML, or the eXtensible Markup Language, is an information description specification that provides a standard method of transferring data from one information system to another, without requiring that the data schema of the two systems match exactly. XML files are self-defining. A new data field can be defined by enclosing the data element between pairs of arbitrarily named tags. For example, to create an XML document of the MyXMLRootTag type with the data element MyXMLDataElementTag, the perfectly legitimate XML syntax would be:

<?xml version="1.0" standalone="yes"?>
<MyXmlRootTag>
<MyXmlDataElementTag>bar</MyXmlDataElementTag>
</MyXmlRootTag>

Leading and trailing white space is clipped off, so there is no difference between this data element:

<MyXmlDataElement>   data     </MyXmlDataElement>

And this data element:

<MyXmlDataElement>data</MyXmlDataElement>

The tags are case insensitive at this writing, so there is no difference between the tags <MYXMLDATAELEMENT> and <MyXMLDataElement>. However, the beginning and closing tags must match exactly for each element. If you try to use this syntax:

<MyXmlDataElement>data</MYXMLDATAELEMENT>

Oracle 9iFS will throw an exception.

Oracle 9iFS exposes the underlying XML handling capabilities of the Oracle9i database, with additional functionality to perform a number of different tasks using XML files.

XML is an evolving standard. The implementation used in Oracle 9iFS is kept at a basic level, using core assumptions that are not likely to change.

Understanding the Different Roles of XML in the Internet File System

There are at least five ways that XML files can be used with Oracle 9iFS, described below. For these descriptions, a persistent XML document is one that appears as an XML document in the Oracle 9iFS folder hierarchy. A transient XML document is one that is uploaded to perform a transaction: the results of that transaction may create a persistent document of another type or change the configuration of Oracle 9iFS, but the XML document itself is not stored as a document in Oracle 9iFS.

Persistent XML Document Stored in Oracle 9iFS

At the most basic level, you can store XML documents in Oracle 9iFS as you would files of any type. You can upload files, create or modify the files with an XML editor, and use the files with any XML application.

Persistent XML Documents Stored in Oracle 9iFS with Parsed Attributes

You can choose to parse the data elements in a persistent XML document and store some or all of the information as custom attributes of the document. The parsed elements will be displayed in the document's Property dialog (both in the Windows and Web interfaces), and you can search on these custom attributes. There are several options available to you for determining how the information will be presented, modified, or rendered by Oracle 9iFS.

Transient Incoming Data Document for Creating Persistent Documents of a Custom Type

For some custom applications, you may want a custom document type to be created, rather than an XML file. You can use an XML file to identify the document subclass for which you want to create a document instance, defining the attributes of the file with XML tags. When you upload the file to Oracle 9iFS, the file is parsed and a document of your chosen subclass is created. The XML file used to create the document does not appear in Oracle 9iFS, and the runtime instance of the document is disposed of once the file has been created.

Persistent Document Rendered as an Outgoing XML Data File

Any document stored in Oracle 9iFS, regardless of how it was created, can be rendered as an XML document. You can control the amount of information rendered using out of the box configuration settings or by creating a custom renderer. The resulting XML document can be transferred to disk, another file server, or used as input to a separate data store.

Transient Incoming Data Transfer Mechanism for Oracle 9iFS Configuration

You can perform many administrative tasks using XML files, including creating new document types, property bundles, access control lists, and other Oracle 9iFS objects. These files are used to modify the Oracle 9iFS schema, or to create or modify persistent metadata used by Oracle 9iFS. The runtime instance of this file is disposed of when the modifications are complete, but the changes are stored as persistent values in Oracle 9iFS.

Using XML Data Files with Oracle 9iFS

When working with XML as a data transfer mechanism, there are several options available involving little or no customization to Oracle 9iFS.

• Storing Persistent XML Documents

• Storing Persistent XML Documents with Parsed Data Elements

• Storing "Roundtrip" XML Documents

Storing Persistent XML Documents

You can store XML documents in Oracle 9iFS as you would files of any other type. You can upload XML files through any protocol, modify the files with an XML editor, and use the files with any XML application.

No customization is required to store XML documents, unless your XML document uses as its root tag a tag that matches one of the reserved root tags for an Oracle 9iFS object. If your XML document uses a reserved root tag, you will need to use an XML namespace to prevent your data element tags from colliding with tags used by Oracle 9iFS. Reserved root tags include the name of any item in the Oracle 9iFS class hierarchy (e.g., Document, Folder, PublicObject) with the inclusion of two special tags, SimpleUser and ObjectList, and tags matching any custom subclass you've created. For more information on namespaces, see Understanding XML Namespaces.

Literal XML documents can also be stored (even when the root tag matches an Oracle 9iFS element) provided parsing has been disabled. It is possible to disable parsing in protocols such as CUP, FTP and the Web interface.

Example 10-1 A Literal XML Document

A document named example.xml with the following contents is stored as an XML document without being parsed.

<?xml version="1.0" standalone="yes"?>
<MyUnrecognizedTag>
<Name>A Name</Name>
<Description>A Description</Description>
</MyUnrecognizedTag>

Name and Description are common tags in many Oracle 9iFS objects, but because the root tag is not recognized, the XML document is not parsed.

DTD Validation

The Oracle 9iFS parser framework can perform document type definition (DTD) validation. A DTD describes the structure of an XML document and specifies validation rules that the document must follow. If the document does not conform to the expected structure of these rules--for example, a required element is missing--the document is invalid. The DTD information can be embedded in the document itself, or it can be stored in an external file.

The Oracle DOM parser can parse a file, compare its contents to the DTD validation rules, and declare the file to be valid or invalid. By default, the parser framework does not validate XML files. Since the decision to validate applies to the entire system, enabling DTD validation requires setting a system property through the Oracle 9iFS Manager.

To enable DTD validation:

1. From the Object menu, choose Register.

2. Select Parser Lookup from the Select Object Type dialog and click Register.

3. Add any document extensions you want to associate with a specific parser class name.

4. In the Parser Lookup Registry Window that appears, check the DTD validation by default option (if currently unchecked).

5. Click OK to close the dialog and apply this systemwide change.

During parsing, Oracle 9iFS checks for the Validate option (passed as an option to the Parse() method. If there is no option passed in, Oracle 9iFS checks the system property and sets the option accordingly. This occurs during the pre-parsing phase. Later, when parsing, the IfsSimpleXmlParser completely ignores the value of the validate option. However, the LiteralDocumentParser takes note of the Validate option to determine whether or not to validate the file. A custom parser can use the Validate option. It can check for the value and pass it to the IfsXmlParser.createDOM() method, or process it any way the developer chooses.

If the XML parser discovers that a file is invalid, Oracle 9iFS generates an error that you can trap in a parser callback mechanism or some other piece of an Oracle 9iFS application. Additionally, the protocol server used to upload the file displays an error message.

If a file is not valid, Oracle 9iFS will not store it. The user needs to correct the errors in the file and upload it again.

Storing Persistent XML Documents with Parsed Data Elements

Oracle 9iFS is a file system but at its heart is the Oracle9i database. A unique ability of Oracle 9iFS is its ability to treat your files both as file instances and as relational data. You have the option of creating a custom parser that will extract selected data elements from your XML documents without changing the document itself. You can still view and edit the documents with any XML application, but you can search for information based on its parsed elements.

To take advantage of this feature, you create your XML document using the Document tag, or a tag representing a custom subclass of the Document class. Recognized tags are stored as attributes of the file, and data enclosed in unrecognized tags are ignored.

Example 10-2 XML Document with Parsed Data Elements

The following XML document, when inserted into Oracle 9iFS, would have its data elements parsed as attributes of the file.

<?xml version="1.0" standalone="yes"?>
<Document>
  <Name>A Name</Name>
  <Description>A Description</Description>
</Document>

Note, however, that the content of this document will be the content of the XML file as shown. You can search on these attributes, and render the document as XML. To create a document with text content (such as an HTML file), you can use the Content attribute tag.

Example 10-3 XML Document with a Content Attribute

The following XML document, when inserted into Oracle 9iFS, would have its data elements parsed as attributes of the file and the information between the Content tags stored as the document's content.

<?xml version="1.0" standalone="yes"?>
<Document>
 <Name>A Name</Name>
 <Description>A Description</Description>
 <Content>Here is the actual content of the document.</Content>
</Document>

Once this document is uploaded, if you were to open this file in the Web interface, the document displayed would read, "Here is the actual content of the document."

Storing "Roundtrip" XML Documents

Roundtrip XML is a new feature in Oracle 9iFS that allows you to store XML files as persistent documents, and then render them out exactly as they went in. This is to meet a specific requirement of some of our customers, who use comment tags to store information or undefined tags to store information they don't want to have parsed by Oracle 9iFS.

By default, when an XML file that deals with Document or subclasses of Document is uploaded to Oracle 9iFS, the document itself is stored in the Content attribute for the file. When the document is rendered, the original XML file is output as it was inserted, including all of its comments and undefined (in Oracle 9iFS) tags.

When using roundtrip XML, there are two important considerations.

1. The document will be rendered from Oracle 9iFS exactly as inserted. Any modifications to the file stored in Oracle 9iFS will not be reflected in the rendered file, unless you write a custom interface that keeps the attributes of the document synchronized with the information in the content attribute.

2. The entire document is stored in the standard Oracle 9iFS content attribute. This means that a roundtrip document cannot define its own Content tag. If you define a content tag, the text in the content tag is stored as the content for the document.

Creating Instances of Custom Subclass Documents with XML

You can create instances of your custom subclasses in the same way you instantiate out-of-the-box objects using XML.

To create an instance of an XML document that will instantiate a custom subclass document:

1. Create an XML file with your custom subclass as the root element.

2. Include entries for all of the required attributes, and as many optional attributes as you like.

3. Upload the file to Oracle 9iFS to create the instance. The attributes available/required depend on the custom subclass you've defined (including its required values) and its parent classes (e.g., Document, PublicObject).

When you use XML in this way, the XML file itself is never stored in Oracle 9iFS. Only the document defined by the XML file is stored.

Example 10-4 Creating an Instance of a Custom Subclass Document with XML

The following XML file, when inserted to Oracle 9iFS, creates an instance of a Shortstory custom document type, with the defined fields Author and Title. The Name attribute is required, and was inherited from the parent class, Document. When this document is uploaded to Oracle 9iFS, a file will appear in the directory to which the file is loaded with the name example.shortstory. The XML file itself will not appear in the directory. The content of the document, when opened in a text editor, would be the text "This is a very short story."

<?xml version="1.0" standalone="yes"?>
<Shortstory>
 <Name>example.shortstory</Name>
 <Author>A Name</Author>
 <Title>A Description</Title>
 <Content>This is a very short story.</Content>
</Shortstory>

Formatting Date Values in XML Data Files

Date values require special handling in XML Data Files. XML is a self-defining language, and the data files need to have built-in support for the data stored within them. Date values require a format parameter be included in the attribute's tag. This way, the XML file can be used with any data store, and the data store will be able to determine the format of the incoming data as it is loaded.

XML uses the same format strings as the java.text.SimpleDateFormat class. Table 10-1 lists a few of the more useful format values.

Table 10-2 shows different ways of formatting the date value February 18, 2001 7:15 p.m.

For more information on Date format strings, see the Javadoc for java.text.SimpleDateFormat.

To define the format used to enter a date attribute in an XML file, you enter the format argument directly in the attribute tag. The syntax is:

<DateAttributeName
  format='formatString'>date_value</DateAttributeName>

Where DateAttributeName is the name of a custom or out-of-the-box date attribute and formatString is a format template using the codes described where that matches the format used to enter the date_value.

Example 10-5 XML File with a Date Value

The following XML file, when inserted to Oracle 9iFS, creates an instance of a previously defined Shortstory custom document type, and populate the defined fields Author, Title, and Pubdate (Publication Date).

<?xml version="1.0" standalone="yes"?>
<Shortstory>
 <Author>A Name</Author>
 <Title>A Description</Title>
 <Pubdate format='MM-dd-yy'>02-18-01</Pubdate>
</Shortstory>

Working with Array Attributes

In some cases, document attributes are composed of arrays of values. To populate array attributes, use the ArrayElement tag.

For example, a Boolean array OpenDays might contain seven true/false values indicating which days of the week a customer's business is open. Boolean values are set using the strings true and false.

.
.
.
<OpenDays>
 <ArrayElement>false</ArrayElement>
 <ArrayElement>true</ArrayElement>
 <ArrayElement>true</ArrayElement>
 <ArrayElement>true</ArrayElement>
 <ArrayElement>true</ArrayElement>
 <ArrayElement>true</ArrayElement>
 <ArrayElement>false</ArrayElement>
</OpenDays>
.
.
.

When setting Date values in an array, each element requires a format parameter, as when setting a single value.

For example, an array of PayDays for the first quarter of the year could be entered as:

.
.
.
<PayDays>
 <ArrayElement format="yy-MM-dd">01-01-15</ArrayElement>
 <ArrayElement format="yy-MM-dd">01-01-31</ArrayElement>
 <ArrayElement format="yy-MM-dd">01-02-15</ArrayElement>
 <ArrayElement format="yy-MM-dd">01-02-28<ArrayElement>
 <ArrayElement format="yy-MM-dd">01-03-15</ArrayElement>
 <ArrayElement format="yy-MM-dd">01-03-31</ArrayElement>
</PayDays>
.
.
.

Using Oracle 9iFS Objects as Attributes

You have the option of storing references to Oracle 9iFS Object types as attributes of a file. For example, when assigning a manager with editorial control over a document submitted to Oracle 9iFS, you can use the manager's DirectoryUser object as the attribute. You can store both single values and arrays of objects.

To use an Oracle 9iFS object as an attribute, you need to identify its reference type (RefType) as a parameter in the attribute tag. An attribute's RefType can take one of four forms, as shown in Table 10-3.

<CLASSOBJECT>

 <Name>TypeDef</Name>
 <Superclass RefType='ID'>
    263
 </Superclass>
 <Description>
    XML demo test class
 </Description>
</CLASSOBJECT>

<PublicObject>
 <Name> Test Object </Name>
 <Document RefType='Path'>
  /docs/test01.doc 
 </Document>
</PublicObject> 

<PropertyBundle>
 <Update RefType="valuedefault">
  ParserLookupByFileExtension
 </Update>
 <Properties>
  <Property action = "add">
   <Name>xls</Name>
   <Value DataType="String">
     MyApplication.Parsers.XLSParser
   </Value>
  </Property>
 </Properties>
</PropertyBundle > 

<PublicObject>
 <Name> Test Object </Name>
 <Owner RefType='DistinguishedName'>
  jdoe@us.oracle.com 
 </Owner> 
</PublicObject> 

Working with XML Namespaces

A namespace is a method of isolating and distinguishing XML tag names used in one context from tags with the same names used in a different context. For example, a company may already have a set of XML data files that use the root tag Document. These files may conflict with the out-of-the-box Oracle 9iFS Document class. Rather than change all of the individual XML files, the company could establish a new namespace and provide special handling for its own files within their defined namespace.

Understanding XML Namespaces

A namespace is identified by a unique name that is a Universal Resource Indicator (URI), usually a Universal Resource Locator (URL). Its use is similar to a World Wide Web domain name. A web domain enables you to define a unique presence on the Internet. For example, the Foo Corporation might have the domain name http://www.foo.com. When any Internet browser in the world is pointed to http://www.foo.com/index.html, the specific page is identified based on the unique domain name, in spite of the fact that there are literally millions of pages named index.html on the World Wide Web.

An XML namespace works the same way. You choose a unique string for your namespace that is not likely to match any other namespace on the World Wide Web. For that reason, it's best to use a registered World Wide Web domain name as the root of your namespace. In the unlikely event that your company does not have a registered domain name, you should choose a namespace string that would be a very unlikely choice for any other entity on the World Wide Web.

The default namespace for Oracle 9iFS, for example, is http://xmlns.oracle.com.ifs. It is a domain name used by Oracle Corporation for the sole purpose of defining unique namespaces for all products. Tags defined for the /ifs namespace will not collide with any other namespace in Oracle Corporation, or any other entity on the World Wide Web.

It's important to note that the URLs do not necessarily point to any document. They are a convenient way to create identifiers that are unique throughout the World Wide Web.

Understanding the XmlParserLookup PropertyBundle

A property bundle in Oracle 9iFS is a cluster of related name-value pairs. Oracle 9iFS is able to locate system metadata by searching for a name in the Property list and retrieving its associated value. This allows you to customize your system, but still enable Oracle 9iFS to predict the name and location of the values it needs.

The XmlParserLookup property bundle is used to identify which parser will be used to handle incoming XML documents. There are four standard values in the XmlParserLookup property bundle, listed in Table 10-4.

If, in all cases, you want to use your own custom parser and never use the IfsSimpleXmlParser, you can update the property bundle and replace the property value associated with the default Oracle 9iFS namespace with the full package name of your own parser. If you want to use the IfsSimpleXmlParser for most documents, but use your own parser for documents of a specific namespace, you will need to create a new namespace. The best way to implement custom behavior is to leave the Oracle 9iFS namespace unchanged, define a namespace for your company, then change the value of the IfsDefaultNamespace property to point to your own namespace.

Creating a Namespace

You create a namespace by adding a new property to the XmlParserLookup property bundle. The property name is the namespace string, and the property value is the full package name of your custom parser.

For example, if you want the http://www.foo.com/myIfsNamespace associated with your custom FooParser, the entry looks like this:

You can create as many namespaces as you need to handle custom parsing requirements. You could, for example, create a separate namespace for each of your customers and associate a parser tailored to meet their individual needs.

In earlier versions of Oracle 9iFS, you were able to create a custom XML parser and use it to handle incoming XML files. For backward compatibility, the CustomXMLParser property is still valid. If a file has a namespace associated with it, but no parser is assigned to that namespace, the CustomXmlParser is used. The entry looks like this:

You can create the namespace using an XML configuration file. To create the namespace for the FooParser, you would use this XML configuration file.

Example 10-6 Creating an XML Namespace with an XML Configuration File

<?xml version="1.0" standalone="yes"?>
 <PropertyBundle>
  <Update RefType="valuedefault">
   XmlParserLookup
  </Update>
  <Properties>
   <Property action='add'>
    <Name>http://www.foo.com/myIfsNamespace</Name>
    <Value DataType="String">
     foo.ifs.custom.parser.FooParser
    </Value>
   </Property>
  </Properties>
</PropertyBundle>

For more information, see "Configuring Oracle 9iFS Using XML Files".

Using a Namespace

Once you've defined the namespaces for your instance of Oracle 9iFS, you can create XML files that use a specific namespace. The namespace is a parameter of the root tag for the XML file. The syntax is:

<RootTag xmlns="namespaceString">

where RootTag is the subclass to be used to instantiate the document and namespaceString is a defined namespace on your Oracle 9iFS server.

For example, Table 10-7 shows an XML file that uses the Foo Company namespace defined above.

Example 10-7 XML File Using a Custom Namespace

<?xml version="1.0" standalone="yes"?>
 <Document xmlns="http://www.foo.com/myifsNamespace">
 <Name>FooName</Name>
 <Description>This is a document for  www.foo.com</Description>
</Document>

When this XML document is inserted into Oracle 9iFS, the parser foo.ifs.custom.parser.FooParser is used to extract its data values.

Rendering XML Data Files

XML files are used not only to transfer information into Oracle 9iFS, but also to transfer information out. Any object, regardless of how it was created, can be rendered as an XML file from Oracle 9iFS.

Files stored in Oracle 9iFS have a great deal of metadata stored with them. Much of that information is useful only within the context of Oracle 9iFS (such as a document's assigned ACL). When rendering XML files, you can control which attributes are rendered and to what level of detail.

Understanding Rendering Options for ClassObjects

Every ClassObject in Oracle 9iFS has an associated PropertyBundle object. The PropertyBundle is named "Class PropertyBundle for <classname>." You can determine which attributes are rendered for each ClassObject by setting three properties in the property bundle:

• IFS.RENDERER.RenderedAttributes

• IFS.RENDERER.InheritSuperClassPolicy

• IFS.RENDERER.InlineRendering

IFS.RENDERER.RenderedAttributes

This attribute is a String Array listing all of the attributes that will be rendered for the ClassObject. If the property is not defined, the extended attributes of the class are rendered and further rendering of inherited attributes is controlled by IFS.RENDERER.InheritSuperClassPolicy.

The three base classes (PublicObject, SchemaObject, and SystemObject) have a set list of attributes defined out of the box. For PublicObject, the list consists of Name and Description. For SchemaObject, only the Name attribute is listed. For SystemObject and Document, the values are set to null. This enables the most useful information to be rendered out (the extended attributes of Document, for instance, are not meaningful outside the context of Oracle 9iFS). You have the option of changing these settings, but an attempt has been made to provide the information that most customers will want to see without having to wade through a large number of system-specific properties.

IFS.RENDERER.InheritSuperClassPolicy

This is a Boolean value. If true, the attributes of the parent class are rendered according to the IFS.RENDERER settings in the parent class. If the parent also has its IFS.RENDERER.InheritSuperClassPolicy set to true, then it will also render the attributes of its parent class, and so on, up the hierarchy.

If false, only the attributes of the ClassObject will be rendered. If a subclass of the ClassObject has its IFS.RENDERER.InheritSuperClassPolicy set to true, attributes will be rendered up through the hierarchy until a ClassObject is encountered with this policy set to false. Only the attributes of that ClassObject and its child objects will be rendered.

If the value of IFS.RENDERER.InheritSuperClassPolicy is not explicitly set, the default is True.

IFS.RENDERER.InlineRendering

This property can take one of three values: Name, ID, or Deep. It is used to define which attributes of the ClassObject will be rendered when the ClassObject is rendered inline as an attribute value of another class.

For example, you might create a custom document type with the attribute Manager, a person who reviews the file prior to its being published. The DataType for Manager can be set to DirectoryUser. The only actual piece of information that will appear in the custom document's data table would be the ID number of the DirectoryUser assigned as the Manager. That may not be the most useful piece of information to export to your XML file, since it's a dumb sequential value meaningful only in its Oracle 9iFS context. The IFS.RENDERER.InlineRendering value lets you choose from three types of inline output for ClassObjects that are used as attributes by other ClassObjects.

Name renders only the Name attribute from the embedded ClassObject.

ID renders only the ID attribute from the embedded ClassObject.

Deep refers to "deep rendering," meaning that it will render the full set of attributes defined for the embedded ClassObject. This takes into account the IFS.RENDERER.RenderedAttributes setting for the embedded ClassObject, and will render only its specified attributes.

When IFS.RENDERER.InlineRendering is not explicitly set, the default behavior will be to try to render the Name of the embedded ClassObject. If the Name is null, Oracle 9iFS will render the ID of the ClassObject.

Setting Rendering Options in ClassObject PropertyBundles

You set the rendering options for a ClassObject as you would set the values for any PropertyBundle in Oracle 9iFS.

Example 10-8 shows an XML file that can used to create a PropertyBundle for the custom subclass Shortstory to include specific attributes, not inherit the display behavior of the parent class, and to use "deep rendering" when it is rendered as an element of another class (that is, it will render all of the attributes listed in the RenderedAttributes property).

Example 10-8 Setting Rendering Options in the ClassObject PropertyBundle Using XML

<ClassObject>
  <Update RefType="name">
   Shortstory
  </Update>
  <PropertyBundle>
    <Name> Class Property Bundle for Shortstory </Name>
    <Properties>
      <Property>
        <Name>IFS.RENDERER.RenderedAttributes</Name>
        <Value DataType="String_array">
          <ArrayElement> Title </ArrayElement>
          <ArrayElement> Author </ArrayElement>
        </Value>
      </Property>
      <Property>
        <Name>IFS.RENDERER.InheritSuperClassPolicy</Name>
        <Value DataType="Boolean">false</Value>
      </Property>
      <Property>
        <Name>IFS.RENDERER.InlineRendering</Name>
        <Value> Deep </Value>
      </Property>
    </Properties>
  </PropertyBundle>
</ClassObject> 

For more information, see "Configuring Oracle 9iFS Using XML Files".

Working with Classes that Require Special Handling

By default, the data elements of certain classes are always rendered. These special cases each have their own Boolean properties that will let you suppress the full detail. For example, by default, all Access Control Entries (ACEs) are rendered when an Access Control List is rendered. But if you only need to see the name of the Access Control List, and not the full detail, you can set the special property IFS.RENDERER.ACCESSCONTROLLIST.ShowAces to false.

There is no inheritance in these special cases. For example, if you have subclassed the PropertyBundle class, this property would have to be set in your class PropertyBundle if you did not want to see its properties. The default when the property is not specified is True.

Table 10-5 lists the properties for classes that require special handling. All of these properties are Boolean values, set to True out of the box.

The content of a file is also a special case. It will be rendered inline if the CONTENTOBJECT attribute is included in the list of attributes for the property IFS.RENDERER.RenderedAttributes.

Configuring Oracle 9iFS Using XML Files

Up to this point, the discussion has focused on working with file content and attributes. Using XML, you're able to identify data elements, and the IfsSimpleXmlParser is able to create and populate a document based on those values. The file is stored in the Oracle9i database as related records in the Oracle 9iFS schema.

But, in Oracle 9iFS, the schema itself is self-describing. The elements of the schema are stored as records in tables as SchemaObjects. Just as you can create PublicObjects by uploading documents with recognized data elements, you can create SchemaObjects by uploading XML documents with recognized data elements.

The upload process is similar to that of uploading a transient XML file to create a persistent custom document. In this case, you upload a transient XML file that describes a SchemaObject. Its parameters are parsed to create the SchemaObject. The XML file itself is never stored in the system. Once the modification has been performed, the runtime instance of the XML file itself is discarded.

Many objects in the Oracle 9iFS class hierarchy can be created using an XML configuration file. The list of objects and parameters for creating XML configuration files can be found in the XML Syntax Reference. The remaining examples demonstrate the use of XML configuration files and highlight some additional considerations for creating specific object types.

Creating a Subclass of the Document Class Using XML

To create a subclass of the Document class, create a new ClassObject. The only required field is the name of the ClassObject we're creating and its Superclass. For example, the Folder class doesn't have any attributes of its own. It inherits all of the attributes it needs from its Superclass, PublicObject. However, Folder requires its own subclass to allow for special processing of Folder objects.

The primary reason for subclassing, however, is to add custom attributes. The attribute definitions are stored separate from the ClassObject definition in the Attributes table. This enables you to add or remove attributes from the ClassObject definition without affecting the base definition of your subclass. Using the entries in the ClassObject and Attribute tables, Oracle 9iFS automatically constructs a new table ODM_<CustomSubclassName> in which to store instances of your custom subclass documents.

Example 10-9 Creating a Subclass of the Document Class

This is the complete listing of XML code that creates the custom Document type Shortstory, followed by commentary. This file can be saved with any name (provided it has the .xml extension). When dropped into Oracle 9iFS, the information is parsed, the objects created, and the runtime instance of this XML file is removed from memory.

<?xml version="1.0" standalone="yes"?>
<ClassObject>

  <Name> Shortstory </Name>

  <Superclass RefType='name'>
    Document
  </Superclass>

  <Attributes>
    
    <Attribute>
      <Name> Title </Name>
      <DataType> String </DataType>
      <DataLength> 1000 </DataLength>
    </Attribute>

    <Attribute>
      <Name> Author </Name>
      <DataType> String </DataType>
      <DataLength> 50 </DataLength>
    </Attribute>

    <Attribute>
      <Name> PubDate </Name>
      <DataType> Date </DataType>
    </Attribute>

  </Attributes>
</ClassObject>

Example Commentary

• The root tag for the custom subclass is <ClassObject>. The ClassObject table stores schema information about the objects in the Oracle 9iFS class hierarchy and your custom subclasses.

• The name of the ClassObject is Shortstory.

• Its parent class, or superclass, is Document. It will inherit the attributes of the Document class, and it will inherit the attributes of the superclass of Document, PublicObject.

• The next tag, <Attributes>, allows you to enter several attribute definitions at once. The attributes are stored in the Attributes table, linked to the custom subclass by the new subclass's ID number.

• Each attribute is defined by specifying its Name and DataType. The first two attributes are String attributes, and require the additional parameter of DataLength. The Date field is stored as a long integer value, so there is no length argument required.

This is a minimal example of a custom subclass definition file. The complete options are described in the XML Syntax Reference.

Creating a Property Bundle Using an XML Configuration File

Property bundles are defined using the <PropertyBundle> element tag. The <PropertyBundle> element can contain an element for each attribute on the PropertyBundle class in the Oracle 9iFS class hierarchy.

The list of name/value pairs, or properties, is specified in a <Properties> element. The <Properties> element is used to enclose <Property> elements that define each Property object in the PropertyBundle.

Each <Property> element contains a <Name> and <Value> element. The <Value> element has the attribute DataType that specifies the DataType for the Property object's value (e.g., String, String_Array, PublicObject_Array). The <Value> element does not directly correspond to an attribute of the Property class. Rather, the value of the <Value> element will be stored in one of the Property attributes, depending on its DataType.

Example 10-10 XML File That Defines a PropertyBundle Object

     <PropertyBundle>
         <Name>pb_test</Name>
         <CreateDate format="dd-MMM-yy">28-Oct-99</CreateDate>
         <Properties>
           <Property>
             <Name> Proptest1 </Name>
             <Value Datatype="String"> foo1 </Value>
           </Property>
           <Property> 
             <Name> Proptest2 </Name>
             <Value Datatype="Date" format="dd-MMM-yyyy">
               28-Oct-2000 
             </Value>
           </Property> 
           <Property>
             <Name> Proptest3 </Name>
             <Value Datatype="Integer_Array">
               <ArrayElement>1</ArrayElement>
               <ArrayElement>934</ArrayElement>
               <ArrayElement>123</ArrayElement>
             </Value>
           </Property>
           <Property> 
             <Name> Proptest4 </Name>
             <Value Datatype="SystemObject" Classname="Policy" 
               RefType="name">
                 SmbXmlRenderer 
             </Value>
           </Property> 
         </Properties>
       </ PropertyBundle>

Each <Property> element can use an Action attribute to specify whether the property should be added or removed from the PropertyBundle. The values for the Action attribute are Add and Remove. For PropertyBundle creation, the Remove attribute does nothing. If no Action attribute is specified, then Add is assumed.

To replace an existing Property, add another property value using the same name. Note that if the same Property is added and removed in the same <PropertyBundle> element, then the remove instruction overrides the add instruction, regardless of the order in which the <Property> elements were declared.

Example 10-11 XML File That Uses the Action Attribute

     <PropertyBundle>
       <Update RefType='Id'>1234</Update>
       <Properties>
         <Property action='add'>
           <Name> Proptest1 </Name>
           <Value Datatype="String"> foo1 </Value>
         </Property>
         <Property action='remove'>  
           <Name> Proptest2 </Name>
         </Property> 
       </Properties>
     </PropertyBundle>

Creating Several Objects at Once Using a Single XML Configuration File

The Oracle 9iFS schema language supports the ability to define an XML configuration file that creates multiple objects. To include more than one object in the XML configuration file, the file must wrap the element declarations with the <ObjectList> tag.

One consideration when creating multiple objects is that the code for all of the objects must be entered properly. If there is a mistake in the XML code, the IfsSimpleXmlParser will stop parsing the file at that object, and none of the objects are created. The only exception to this is the creation of ClassObjects and DirectoryUsers. These two object types are explicitly committed. If there is an error when creating objects of these types, you need to modify the XML file and delete the definitions of objects already created.

Example 10-12 Creating Multiple Objects with a Single XML File

This XML Configuration file creates two Folder objects in the home folder named foo and goo, then creates a Document object name Test document and stores it in the /home/goo directory.

     <?xml version = '1.0' standalone = 'yes'?>
     <ObjectList>
       <Folder>
         <Name> foo </Name>
         <FolderPath> /home </FolderPath>
       </Folder>
       <Folder>
         <Name> goo </Name>
         <FolderPath> /home </FolderPath>
       </Folder>
       <Document>
         <Name> Test document  </Name>
         <FolderPath> /home/goo </FolderPath>
         <Content> This is the content </Content>
       </Document>
     </ObjectList>