Table of Contents
We will discuss in this chapter a few advanced topics related to YaTiSeWoBe. Users don't need to read this information, but understanding those questions can help to take real advantage of the technical solutions we chose for YaTiSeWoBe implementation. You will find details on the native document format in Section 5.1, “Documents”, the management of LAN installations for a group of collaborating users in Section 5.2, “Managing distributed installations”, and the scripting facilities in Section 5.3, “Jython console”.
An interesting aspect of YaTiSeWoBe is that the documents it opens are not the date files themselves. The manipulated documents are a description of where to find the data, and what to do with it. This comes from the ability of YaTiSeWoBe to merge data coming from several files, locations, and formats into the same document and from the design decision to keep data at a single location the user or a group of users have access to. Read Section 3.2, “Handling data” for more information on the way YaTiSeWoBe is designed to handle data.
Typical users will certainly never check the details of the native document format of the applications, but understanding how it is organized will help using YaTiSeWoBe more efficiently. Power users, wishing for example to generate those documents programmatically to feed them into YaTiSeWoBe are the real target for the next sections.
We will discuss both the native document format and the template variant. Their details are inspired on the OpenOffice.org [43] file format [44], and on the bundles [18] used for Apple Mac-OS X [17] applications.
As expressed in Section 3.2, “Handling data”, data is defined by its source (URI/URL) and format (MIME-type). The methods applied to the data are contained in pluggable elements that can have many different properties, styles and settings which are completely unknown for YaTiSeWoBe.
Instead of creating a huge binary file obscurely containing data, style-sheets, … we chose to create an organized structure of sections: simple XML files and directories with naming conventions. The native document format (*.yati files, MIME-type: application/x-nhrg-yatisewobe-document) are a set of XML files organized with a determined structure and compressed into a ZIP archive on the fly. If you decompress a .yati file with a un-zipper tool, you will uncover a directory structure looking like:
Example 5.1. Structure of a native file
The structure of the contents of a .yati file are shown and described.
<root>| +- content.xml
+- catalog.xml
+- meta.xml
+- settings.xml
| +- class
| | | +- class#1 | +- class#2 | +- … | +- data
| | | +- datafile#1 | +- datafile#2 | +- … | +- META-INF | | | +- manifest.xml
| +- plugin
| | | +- plugin#1 | +- plugin#2 | +- … | +- style
| +- style-sheet#1 +- style-sheet#2 +- …
| Virtual root of the hierarchy. |
| XML description of the contents of the document: which view and information appears, where it appears, … |
| an XML file describing where to locate the data. This file is used to convert from relative to local/distributed or zipped locations. Tweaking this file can be incredibly powerful. |
| … |
| … |
| if the author of the document knows that she is using custom classes, they can be included in this document subdirectory. User will be proposed whether to install those classes. |
| Optional subdirectory containing the included data files. Data can be partially placed in this subdirectory, but a better way is to use the catalog to map the files to an available data repository, as explained in Section 3.2, “Handling data”. |
| … |
| if the author of the document knows that she is using custom plug-ins, required classes can be included in this document subdirectory. User will be proposed to install those classes at the "user" level (read Section 3.3.2.4, “User level plug-ins”) or to use them only for this document (read Section 3.3.2.5, “Document level plug-ins”). |
| Style-sheets required by the different view plug-ins might require to display the data. |
![[Note]](images/note.png) | About the YATI acronym |
|---|---|
For Star-Trek fans chatting on the web, YATI happens to be the abbreviation of Yet Another Trek Inconsistency, but YaTiSeWoBe native file extension has not been chosen because the Star-Trek TV series contain time inconsistencies. | |
To make a long story short: the native file format is just a ZIP file with some naming conventions for particular files inside it.
We have seen the different sections of the document, and we will now take a closer look to each of them. Each data file having its own format, we will present no examples for them. Note that the native file format for YaTiSeWoBe is entirely described in Appendix D, Data format.
Example 5.2. Document content section example
<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
<content:content
xmlns:content="http://yatisewobe.nhrg.org/schema/content"
xmlns:data="http://www.nhrg.org/schema/data">
<content:charts>
<!-- first chart -->
<content:chart view="org.nhrg.apps.rv.special.RasterViewPlugin"
style="sheet001.xml" duration="5000" selected="true">
<content:trigger/>
<content:selection>
<data:selector>
<data:type source="source001" code="0x52"
qualifier="0x0" mask="0x0" />
</data:selector>
</content:selection>
</content:chart>
<!-- second chart -->
<content:chart view="org.nhrg.apps.rv.view.HistogramViewPlugin"
style="sheet002.xml" duration="8000" selected="false">
<content:trigger>
<data:selector>
<data:type source="source001" code="0x52"
qualifier="0x0" mask="0x0" />
</data:selector>
</content:trigger>
<content:selection>
<data:selector>
<data:type source="source002" code="0x52"
qualifier="0x0" mask="0x0" />
<data:type source="source002" code="0x1"
qualifier="0x1" mask="0xFFFF" />
</data:selector>
</content:selection>
</content:chart>
</content:charts>
</content:content>
Example 5.3. Native document: settings section
<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
<settings:settings
xmlns:settings="http://yatisewobe.nhrg.org/schema/settings">
<settings:property
name="http://yatisewobe.nhrg.org/setting/rows">6</settings:property>
<settings:property
name="http://yatisewobe.nhrg.org/setting/cols">6</settings:property>
<settings:property
name="http://yatisewobe.nhrg.org/setting/instance-example">
<java version="1.0" class="java.beans.XMLDecoder">
<object class="javax.swing.JFrame">
<void property="name">
<string>frame1</string>
</void>
<void property="bounds">
<object class="java.awt.Rectangle">
<int>0</int>
<int>0</int>
<int>200</int>
<int>200</int>
</object>
</void>
<void property="contentPane">
<void method="add">
<object class="javax.swing.JButton">
<void property="label">
<string>Hello</string>
</void>
</object>
</void>
</void>
<void property="visible">
<boolean>true</boolean>
</void>
</object>
</java>
</settings:property>
</settings:settings>
Details about XML catalogs are located in Section 3.2.1, “Resolving URIs/URLs with XML catalogs”.
Example 5.4. Native document: catalog section
<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
FIXME!!!
<!-- DTD and style-sheet files installed under /usr/share/xml -->
<group xml:base="file:///usr/local/docbook/">
<!-- Resolve DTD URL system ID to local file -->
<rewriteSystem
systemIdStartString="http://www.oasis-open.org/docbook/xml/current/"
rewritePrefix="xml/" />
<!-- Resolve style-sheet URL to local file -->
<rewriteURI
uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
rewritePrefix="xsl/" />
<!-- Resolve DTD PUBLIC identifiers -->
<nextCatalog catalog="xml/catalog.xml" />
<!-- To resolve simple DTD SYSTEM identifiers. -->
<!-- Note: this does not work with Java resolver -->
<!-- classes in Saxon or Xalan -->
<system systemId="docbook.dtd" uri="docbookx.dtd" />
<!-- To resolve short style-sheet references -->
<uri name="docbook.xsl" uri="html/docbook.xsl" />
<uri name="chunk.xsl" uri="html/chunk.xsl" />
<uri name="fo-docbook.xsl" uri="fo/docbook.xsl" />
</group>
</catalog>
![[Important]](images/important.png) | Future feature |
|---|---|
As of version 0.1.2, functionalities described in this section have not been fully implemented yet, but are already planned for future releases of YaTiSeWoBe. See Section 6.8.2, “Forseable releases” for more details. | |
Example 5.5. Native document: style-sheet section
<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
<sheet:style-sheet
xmlns:sheet="http://www.nhrg.org/schema/style"
xmlns="http://www.nhrg.org/schema/style"
class="org.nhrg.apps.rv.special.RasterViewPlugin"
id="overhead" version="1.0">
<!-- styles -->
<sheet:styles>
<!-- first style -->
<sheet:spot backgroundcolor="#ffff00"
class="org.nhrg.graph.style.impl.RectSpotDrawingStyle"
foregroundcolor="#000000" height="3"
id="spots" width="3">
<sheet:stroke
class="org.nhrg.graph.style.impl.PlainStrokeStyle"
dasharray="FIXME" dashphase="0.0" endcap="2" id="Stroke"
linejoin="0" linewidth="0.0" miterlimit="10.0"/>
</sheet:spot>
<!-- second style -->
<sheet:path class="org.nhrg.graph.style.PathDrawingStyle"
color="#ffff00"
id="trigPath">
<sheet:stroke
class="org.nhrg.graph.style.impl.InterruptedStrokeStyle"
dasharray="FIXME" dashphase="0.0" endcap="2" id="Stroke"
linejoin="0" linewidth="1.0" miterlimit="10.0"/>
</sheet:path>
</sheet:styles>
<!-- attributes -->
<sheet:attributes>
<sheet:color id="background" value="#0000ff"/>
</sheet:attributes>
</sheet:style-sheet>
| Future feature |
|---|---|
As of version 0.1.2, functionalities described in this section have not been fully implemented yet, but are already planned for future releases of YaTiSeWoBe. See Section 6.8.2, “Forseable releases” for more details. | |
Templates contain the answer to the question "what to do with the data?" without specifying "which data" to manipulate. They are a convenient way to automatize the treatment of a group of files and can be considered as a kind of meta-view.
There are no deep differences between native and template files except. Template documents are incomplete native documents, where associated data files and maybe some properties are not defined. All native files are valid template files (*.yate files, MIME-type: application/x-nhrg-yatisewobe-template) if the associated data is disregarded. This is pretty convenient, as you can create templates easily from existing documents, and apply templates to data just by associating it.