Using files

When an ODA that implements the IGeneratesBinFiles interface, it can support the use of operating-system files in the following contexts:

Creating files for file content

When an ODA implements the IGeneratesBinFiles interface, it supports creation of files as content. The files that the ODA creates hold the information that the ODA collects from the business-object-definition generation process and elsewhere. If the file-generation process needs the array of user-selected source nodes (which Business Object Wizard creates as a result of Step 3, Select Source), the ODA can receive this array from Business Object Wizard. For information on how to implement the method that generates the files, see Generating files.

However, the IGeneratesBinFiles interface does not define a source-node-generation method, which discovers source nodes and generates the array of tree nodes for Business Object Wizard to display in the Select Source dialog box. Instead, if the ODA supports generation of file content and this file generation requires an array of user-selected source nodes, the ODA must use the source-node-generation method in the IGeneratesBoDefs interface, getTreeNodes(). This method queries the data source for the child nodes of the specified parent node and constructs the associated tree nodes, as described in Generating source nodes.

Note:
In this release, every ODA is required to support generation of business object definitions. Therefore, it must implement the IGeneratesBoDefs interface and all its methods (including the getTreeNodes() method).

If an ODA supports only creation of new files (file generation), it can use the getTreeNodes() method as defined in IGeneratesBoDefs. This method queries the data source for the child nodes of the specified parent node and constructs the associated tree nodes, as described in Generating source nodes.

Reading files for source data

When an ODA implements the IGeneratesBinFiles interface, it can support reading operating system files that you associate with source nodes (For information on how to associate a file with a node, see Associating an operating-system file.). The files that the ODA reads hold source data, which the ODA must search for objects that are represented as source nodes. To support the association of files with nodes, an ODA must take the following steps:

Important

An ODA must implement the IGeneratesBinFiles interface for the getClientFile() method to successfully retrieve a specified operating-system file. If the ODA implements only the IGeneratesBoDefs interface, getClientFile() throws the UnsupportedContentException exception.

The getClientFile() method expects as an argument the source-node path of the file to retrieve. This source-node path has the following format:

fileNodePath:filePath
 

where fileNodePath is the node path (node names separated by colon (:)) of the node that has an associated file and filePath is the operating-system path of the associated file. When users expand or select a node that is an associated file, Business Object Wizard creates this path for the node.

For example, the ArmyAgent5 class of the sample Roman Army ODA supports both the IGeneratesBinFiles interface and the association of files with nodes. Suppose you associate the Flavius.xml file (in the directory C:\IBM\XMLFiles) to the Vulso source node, as shown in Figure 49.. If you select the Flavius.xml node (see Figure 50) from the source-node hierarchy, Business Object Wizard puts the following node path into the array of source nodes:

Apollo:Vulso:Flavius.xml:C:\IBM\XMLFiles\Flavius.xml
 

This ODA provides the findSon() method to parse a source-node path and locate the associated object that the source node represents. The version of findSon() in the ArmyAgent3 class queries only the ODA's data source (an XML file called RomanArmy.xml) for the object associated with the specified source node. A revised version in the ArmyAgent4 class adds the ability to query an associated file by providing the remoteSon() method, which uses getClientFile() to obtain the contents of the specified file and return this content as a Son object.

Note:
The ArmyAgent4 class, which implements the remoteSon() method, does not support the IGeneratesBinFiles interface. Therefore, the remoteSon() method catches the UnsupportedContentException exception that getClientFile() throws and creates a "dummy" Son object (see Figure 76). The ArmyAgent5 class, which extends ArmyAgent4, does implement IGeneratesBinFiles. Therefore, this version of the ODA can fully support access to files associated with source nodes with getClientFile().

If a source node can have a file associated with it, then the ability to interpret the file's source-node path and to read the contents of this file is needed during content generation, the method that generates content must be able to access information in nodes that are in a file. Implement the method that generates content so that it uses getClientFile() to retrieve an operating-system file that is associated with a node. The method that provides this support is as follows:

For more information on how to generate file content, see Generating files.

Copyright IBM Corp. 1997, 2004