ASG-Rochade XML Facilities Readme

Transcription

1 ASG-Rochade XML Facilities Readme Version January 07, 2006 This file contains product information, installation instructions, and information about starting and using ASG-Rochade XML Facilities (herein called XML Facilities). Note: ASG encourages you to visit and sign onto the Intelligent Support Portal (ISP) to verify whether any product or documentation revisions, new maintenance, or service packs apply to this release of the product or its accompanying documentation. Product Overview XML Facilities consists of: AutoPilot XML Import/Export Facility (an Rochade plug-in) This is a shared library (DLL) to be used as a Rochade plug-in. It uses the XML Facilities (SAX2) API (see below) and implements dedicated import and export features for AutoPilot users. Installing the plug-in adds these entries to the Tools menu in the AutoPilot main window: Import SAX-Import Export SAX-Export This plug-in can also be used directly within Rochade procedures. AutoPilot XML Import/Export Facility GUI This is an AutoPilot-integrated GUI to control the AutoPilot plug-in. Rochade XML Import/Export batch driver command line tools These are XML import and export tools that act as separate Rochade clients. Their functions are based on the XML Facilities (SAX2) API. There are a number of command line parameters that control the import and export processes. Copyright 2006 ASG GmbH & Co. KG, a wholly owned subsidiary of Allen Systems Group, Inc. All rights reserved. All names and products contained herein are the trademarks or registered trademarks of their respective holders. 1

2 Rochade XML Facilities (SAX2) API. These facilities consist of a shared library (DLL), C++ include files, an import library, and an API documentation. You can use them to develop Rochade applications that have a main focus on processing XML documents, taking advantage of these characteristics: This API has a simple and straightforward object-oriented design. Since there is no need to use C++-style pointers on the part of the application, the programming style is similar to Java. The design is based on a simple object model. All objects in this model can be addressed by URL-like strings. The SAX2 API as part of the XML Facilities (SAX2) API is implemented according to the industry standard defined at It supports these activities: Loading and parsing of XML data from different sources (usually files, URLs, etc.), including Rochade Filtering and transforming of XML-coded data Writing XML data to various targets, including Rochade Installation Information ASG provides detailed lists of hardware and software requirements for all Rochade components and relevant operating systems in its ISP under Hardware Requirements Minimum system requirements: Pentium I or compatible processor, 200 MHz 64 MB RAM, 128 MB preferred 20 MB of free disk space. During installation you will temporarily need about 30 MB of free disk space. 2

3 Software Requirements This software should be installed on your computer: Microsoft Windows 95/98/NT/2000/XP Rochade Client Version or later AutoPilot Version or later Internet Explorer Version 5.0 or later Microsoft HTML Help Viewer (.chm browser) Note: The Microsoft HTML Help Viewer is a standard part of Windows 2000 and Windows XP. WinNT4 and Win9x users may need to install the Microsoft HTML Help Viewer by running the program \optional\hhupd.exe, which is provided on the installation CD. Third-party Software and References Installation Steps This product includes software developed by the Apache Software Foundation (see and utilizes the Apache Xerces-C++ XML parser (xerces-c_x_x_x.dll) and the Apache Xalan-C++ XSL/T processor (xalan-c_x_x_x.dll). For license conditions, see the files xerces-c_license.txt and xalan-c_license.txt. See also these references: To install XML Facilities, follow the general directions given in the readme_en.pdf file for installing Rochade applications. Like all Rochade applications, XML Facilities is installed in two steps: 1 ADM installation 2 Application installation During the installation procedure, XML Facilities is referred to as rosax. 3

4 Getting Started Reading or Writing XML-coded Data from or to Rochade To read or write XML-coded (meta)data from or to Rochade 1 Define the set of (meta)data to be read (e.g., by creating a list of Rochade items), or select a target application. 2 Transform the Rochade items and their relations according to a set of rules into one of the available XML formats, or transform from one of the available XML formats to Rochade items. The set of rules for generating XML from Rochade (meta)data and for processing an XML document for Rochade consists of these parts: XML (.xdr) schema (itself an XML document) XML mapping specification (itself an XML document) These XML formats can be generated and processed: RNX (Rochade Native XML): A proprietary, Rochade-optimized XML format that represents a persistent implementation of the Rochade object model. XMI 1.0 (XML Metadata Interchange): The metadata exchange format of the OMG (Object Management Group). OIM (Open Information Model): The metadata exchange format of the MDC (Meta Data Coalition). Various XML formats can be installed (involving an XML schema and an XML mapping specification for each format) and registered with the AutoPilot Plug-In. This is the way metadata source applications (e.g., scanners and buses) can provide their XML formats to be used by the system. There is a placeholder Other Vocabulary, where users can directly specify the XML schema and mapping specification documents to be used by the next import or export process. You can intervene at each processing level by using C++ or Rochade procedure language. 4

5 AutoPilot Plug-in for XML Import and Export To use the AutoPilot plug-in for XML import and export 1 Start AutoPilot 2 Select Tools Import SAX-Import to start the XML import. Or Select Tools Export SAX-Export to start the XML export. 3 Complete the import or export as required by the subsequent dialogs. These dialogs are, for the most part, self-explanatory, but there is an integrated context-sensitive help function that provides guidance in case there are questions about their features. Batch Driver Command Line Tools To use batch driver command line tools Enter rcsaximp on the command line to start the XML import tool. Or Enter rcsaxexp to start the XML import tool. The import and export batch driver command line executables are installed in the <rochade>\bin directory. These are XML import and export tools that act as separate Rochade clients. If you run the executables without any parameters or with incorrect parameters, they will write a summary of the valid parameters to the console. Using XML Facilities (SAX2) API In the <rochade>\samples\sax directory, you will find several examples that demonstrate how to use the C++ API of Rochade XML Facilities. The directory contains these subfolders, which have been installed by this product release: Directory.\RoSAX.\RoSAX\SAXImport.\RoSAX\SAXExport.\RoSAX\SAXFilterChain.\RoObj Description Contains all XML import/export-related examples Contains the XML import command line example Contains the XML export command line example Starting with release , this example is no longer supported Contains all examples for object-oriented Rochade access 5

6 Directory.\RoObj\RoInform.\RoObj\RoObjectModel./RoObj/RoWorkArea.\RoObj\RoQuery.\XSLStyles.\HTTPOutputTarget.\RoJava Description Demonstrates how to call RPL commands and use the $INFORM callback handler Demonstrates how to use the object hierarchy to browse a Rochade dataspace Demonstrates how to use Rochade work areas in C++ Demonstrates how to use C++ query objects Contains some XSL/T sample style sheets for application when using the integrated XSL/T processor. This is the virtual root folder for the embedded HTTP server (HTTPOutputTarget). It contains some icons. Starting with release , this example is no longer supported, since these files are part of another ASG product. Documentation ASG provides this documentation for the product: ASG-Rochade XML Facility Users Guide (part of the documentation CD) The installation deposits this documentation in the installation target directory: Documentation Online help XML Facilities (SAX2) API documentation File Name (and Path) <Rochade>\help\en\SaxTutorial.chm <Rochade>\TechDoc\sax\en\rosax.chm Enhancements and Changes Version Version Supports HP-UX 11. Increased tolerance regarding unmapped elements and their sub elements. Rochade XML Facilities will continue importing while those issues are reported as warnings. The warnings are collected in the error file, usually named ROSAX.ERR. 6

7 To handle attempts to map XML attributes to Rochade link attributes, this warning has been incorporated: Could not resolve the XML attribute attribute_name. This XML attribute is mapped to the Rochade Lnk attribute attribute_name of the item type item_type. The mapping of XML attributes to Rochade Lnk attributes is not (yet) supported. Only XML elements can be mapped to the Rochade attribute attribute_name. Improved the handling of apparent information model mismatches between export and import. The import will continue silently, and after the import, a warning message similar to this will appear in the error file: The current import file was created on the basis of a Rochade information model (RIM) with the name rim_name_1. But the selected Rochade application is based on RIM rim_name_2. The import will be successfully completed only if both information models contain compatible structures. Improved unified handling of link concept 1 and link concept 2 databases. Handling of inactive items in non-hierarchical applications in link concept 1 databases has been corrected. While the export still attempts to evaluate a version number from the name of the information model (in order to export it in the XML/XMI header), the exported name of the information model itself is no longer truncated or modified. So the name of the information model will be exported in the XML/XMI header in its original form. The problem of disappeared inactive link target items in link concept 1 databases has been fixed. The bug has been fixed that occurred if one and the same link attribute was written very often (e.g., 128 times) during an import due to distributed references between the XML elements in the XML document. 7

8 Version Improved the XMI1.0 import and export: The XMI import creates Rochade items according to the most specialized XML elements in the XMI input file. For example, it now creates an UML_ABSTRACTION item if it recognizes a <Foundation.Core.Abstraction xmi.id =... > element, even if <Foundation.Core.Dependency xmi.idref =... > elements occur earlier in the same XML document with equal xmi.id identifiers. Enabled XMI1.0 import and export in FLAT subject areas with qualified names. The naming of items follows the rules in the mapping file. Enabled XMI1.0 import and export in TREE subject areas with hierarchical names. Hierarchical names are generated if the item types in the information model contain namespace attributes. Improved interoperability in TREE subject areas (with hierarchical names): If the item types that are involved do not contain namespace attributes, no namespace relationships are created and the items are named according to the rules that normally apply in FLAT subject areas (with qualified names). This enables XML Facilities to work the same way with TREE subject areas as with FLAT subject areas where this is needed in combination with other tools. In some XML exports, the links within a link attribute in the generated XML file were ordered in a manner that differed from the order within the attribute stored in Rochade. This is now fixed. Sometimes, after export/import in a link concept 1 database, the link target items no longer existed. This has been corrected. In some situations, especially in XMI imports, there were misleading warnings when using namespace attribute mappings, similar to this: Could not resolve... 'UML_N-OWNED-ELEMENT', that is mapped to the... XML attributes that are not mapped to Rochade attributes but are, in fact, mapped to the link information of a Rochade link are no longer reported as unmapped XML attributes. 8

9 Version Introduced the ridetermineby mapping rule as a solution to deal with cases where multiple identical naming identifiers exist in the same scope that map to identical Rochade item types. The new mapping rule allows you to define how different Rochade items should be determined and uniquely named during the import. These are the valid rules: id: Different XML ids should map to different Rochade items even if the item name generation rules create identical names for different items of the same type (in which case the names will be modified to make them unique). name: If the item name generation rules create identical names for different XML ids and the corresponding XML elements are mapped to the same Rochade item type, then different XML elements will still modify the same item (according to the import modes or processing instructions). ASG released the Rochade Native XML (RNX) vocabulary 1.2 with these minor changes: The xmi.uuid and xmi.uuidref XML attributes are now optional. They are excluded (i.e., commented) in the schema so that they are no longer exported for items and links in RNX format. If you want them to be exported, include them in the schema (i.e., remove the comments). The linktype XML attribute is now optional. It is excluded (i.e., commented) in the schema so that it is no longer exported for link attributes in RNX format. If you want it to be exported, include it in the schema (i.e., remove the comment). The rcsaximp and rcsaxexp import/export batch driver command line executables are now installed in <Rochade>/bin. You still find the sources of these as examples for how to use the XML Facilities (SAX2) API in the <Rochade>/samples folder. ASG has changed the default parameter setting in all command line examples for the -d=xxx parameter (to specify the value for the property The new default setting is -d=" ". In addition, the default settings in the rcsaximp import batch driver command line tool for the -wi=xxx parameter (to specify the import mode for Rochade items) has been changed. The new default setting is -wi=scr (where scr stands for scratch). The handling of link qualifiers containing Rochade special characters has been improved. In order to preserve Rochade special characters in link qualifiers, standard (formatted) T-type link attributes are exported using $SLI (with the new U/V flags) and imported using $WRITE. Items whose names begin with a colon (:) can now be handled correctly. 9

10 In link concept 1 databases, inactive versions of "referenced only" link targets were always created, even if they were already visible in the configuration path. This has been corrected. The problem that occurred when running an import/export in a copied database has been resolved. There was an error in the Messages tab of the XML Facilities Export and Import windows in AutoPilot. The Browse buttons called a Windows Open File dialog, so that the user was not able to set this to a file that did not yet exist. These buttons now call the Save File dialog. This version handles the $OPTION APNAMES correctly when using XML Facilities in AutoPilot. The option is set to OFF before importing/exporting, and it is reset to the previous value afterwards. The rcsaximp and rcsaxexp import/export batch driver command line executables prompted for a second user logon/password input in case of wrong input, but terminated without actually allowing the input. This has been corrected. If an XML dataspace file is used to preconfigure Rochade servers, databases, and user logins, then a preconfigured password was also used for subsequent logins. This has been corrected. Improvements have been made for these XMI-related import and item naming issues: Handling the case where an XML element is referenced by an inverse link before it is defined in the XML import stream. Handling the case where the mapping and name generation rules result in item names containing white spaces only. Handling the case where the mapping and name generation rules result in empty item names. Handling the case where an XML element is referencing itself. Handling the case where an XML element is defined in the XML import stream before the element providing its scope is defined. There was this issue involving FLAT subject areas with qualified names: Certain items, such as UML_CLASS items, had no correct qualified names. The problem has been solved. A solution has been integrated for the case where namespace children could not be distinguished within the same scope and thus resulted in a single Rochade item. 10

11 Version In the Rochade Native XML vocabulary (RNX), the ITEM element now has a new attribute modstamp. This attribute is filled during RNX exports and contains the value of the &STAMP system attribute of the exported item, and through this, information about the last modification of the item contents (time of last modification and the user who made it). Since the &STAMP system attribute refers to the item contents, it is processed according to these rules during RNX imports: If the imported item did not exist at the target or was not visible before the import, it is created. The item contents is completely copied from the XML export file into the target item. In this case, the value of the &STAMP attribute is restored from the value found in the modstamp attribute in the XML file. If the item already existed before the import and the import uses the Item Scratch Mode of XML Facilities, the existing contents is erased. Also in this case, the new item contents is copied in completeness from the XML file into the target item. So the value of the &STAMP attribute is restored from the value found in the modstamp attribute in the XML file. If the item already existed before the import and the import uses the Item Modify Mode of XML Facilities, the import may update or add new attribute contents to the existing item. So the contents of the target item gets modified. In this case, the value found in the modstamp attribute in the XML file is ignored. Instead, the &STAMP attribute is updated using the current date, time, and user (i.e., member of the subject area). Note: The export of the modstamp attribute depends on the new RNX XML schema (RNX_1_2.xdr), which is included in this release Older releases of the schema will not export the new attribute. If the modstamp attribute is not found in the XML file, the &STAMP attribute is updated using the current date, time, and user (i.e., member of the subject area). XML imports using logical vocabularies (e.g., XMI) create new physical item contents from the XML documents. So the &STAMP attributes of the created or modified items are always updated using the current date, time, and user (i.e., member of the subject area). The bug that caused the export file to remain locked after an abnormal end (i.e., cancel or error) of an XML export has been fixed. During an XML export from a subject area hierarchy, namespace members with a HIDDEN state on the work configuration were reported as dummy items. The problem has been fixed and the visibility of exported namespace members is ensured now. 11

12 Version If an XML import should have resulted in a dummy item (due to references) located in the namespace of a scope item (due to existing namespace attribute and corresponding nesting), the expected dummy item turned active by mistake. This has now been fixed. After an XML export, namespace relationships were missing if a namespace child preceded its namespace parent (scope item) in the export set. In such a case, there should be a normal reference in the XML element that corresponds to the namespace attribute. This works correctly now. An exception is no longer thrown when a namespace attribute has an empty list of target types or if all target types are deselected from the view of an application. This will cause the namespace attribute to be exported as empty. The program no longer tries to read attribute information from the RIM for the types of dummy items. The issue, which prevented the export of item lists, has been fixed. It is now again possible to export item lists. There was an issue that arose when items in the XML import file referenced themselves and the referencing tag closed on the same line as the entity tag closed. This issue has been fixed. An issue concerning the handling of the &OWNER system attribute has been fixed. The &OWNER system attribute refers to the user (i.e., member of the subject area) who created the item, and it is processed in accordance with these rules during XML imports: If the imported item did not exist at the target or was not visible before the import, it is created. The &OWNER system attribute is updated with the current user. If the item already existed before the import, the existing value of the &OWNER system attribute is preserved. Since the &OWNER attribute is processed internally, there is no need to export its values into XML during XML exports. When writing T-type link attributes, XML Facilities generated item names for the link targets with an escape character (@) at the first position. This became obvious when comparing link attributes written by XML Facilities with link attributes written by JavaAPI-based products. This has now been fixed. If the rilength attribute was used in XML mapping documents with a value >=32, XML Facilities posted an error message that did not pertain directly to the issue that needed to be addressed. This has now been fixed. Some users reported a value NIL in value attributes that should have been empty. This version contains a solution for this issue.

13 Version Version Version Version In Rochade Native XML vocabulary (RNX), items that are not in the export set but are referenced by items that are in the export set, are normally exported as empty XML elements. These empty elements in the XML exports serve as targets for XML references within the XML documents. The prior release contains a bug that generates these empty elements also when they are not necessary. This does not do any damage to the data, but it leads to misinterpretation of the exported XML documents, for instance, in subsequent XSLT transformations. This release supports the extensions of the Rochade 7.00 kernel Beta I release. This release supports the Rochade 7-based extensions regarding namespace attributes. If the XML import recognizes an application with a Rochade 7-based and migrated information model with namespace attributes, it generates corresponding namespace relationships. This release supports additional Rochade 7-based extensions: If the XML import/export recognizes an application with a namestruct setting TREE (i.e., with support for naming hierarchies), it searches for namespace attributes in all item types that are mentioned in the mapping file. If no namespace attributes are found, the application is handled like an application with namestruct setting FLAT. This allows you to use XML Facilities in applications with RIMs that are composed of hierarchical and flat parts. Therefore, when you import in a flat submodel of such an application, XML Facilities generates corresponding qualified item names. Some messages and warnings have been improved. XML Facilities reported a string 'NIL' in RPL handlers where just NIL was expected. This has been fixed now. Incorporated support for ordered namespace attributes. Contains the changes that were required for porting the Rochade 7-based enhancements in this technology to various UNIX systems. 13

14 Issues, Restrictions, and Known Problems This release does not support transactions and item locking features. Compatibility This release is compatible with the XDR schema syntax. It is not compatible with the XSD (W3C) schema syntax. This release is compatible with XMI1.0. It is not yet compatible with XMI1.1 or later releases. ASG released the Rochade Native XML (RNX) vocabulary 1.2 with minor changes. For details, see the relevant bullet in Version on page 9. ASG has changed default settings involving the parameters -d=xxx and -wi=xxx. For details, see the relevant bullets in Version on page 9. 14