ViewVC logotype

Contents of /trunk/projects/dm/vo-dml-org/README.txt

Parent Directory Parent Directory | Revision Log Revision Log

Revision 4146 - (show annotations)
Tue Jul 11 08:52:16 2017 UTC (3 years ago) by lmichel
File MIME type: text/plain
File size: 9835 byte(s)
Old folder renamed. Should be removed soon
2 ----------------------------------
4 This project contains a definition of a VO Data Modelling Language, VO-DML,
5 models built accoring to the language and various scripts to validate these and build derived data products from them.
6 The folder structure is as follows:
8 <root>
10 - ./build.xml
11 ant build file with targets used for generating a vo-dml representation of a particular type of model XMI file,
12 as well as generating HTML and utype-s from the vo-dml representation.
13 See the end of this file for an explanation of the main ant targets.
15 - ./build.properties
16 See documentation inside the file and the description of build.xml at the end of this file.
18 -./doc/
19 Folder containing VO-DML and UTYPE specifications, as well as some earlier document mainly created during the utype tiger team.
21 -./doc/examples/
22 Folder containing some example VOTable documents with various types of UTYPE based annotation.
23 Also files containing object instantiations derived from such VOTable files.
25 - ./models/
26 Folder containing specific IVOA models in VO-DML form together with generated HTML documentation.
27 Each model has its own folder.
29 Most models are derived from an XMI file, contained in the model specific folder.
30 Each folder MUST contain a file called vo-dml.properties so that the ant tasks can use it.
31 This file MUST contain a property named 'dm.filename.prefix', which governs the names of all generated files:
32 <dm.filename.prefix>.vo-dml.xml gives the name of the VO-DML representation of the model.
33 This is used as source for generation from the vo-dml/xml rep to for example HTML.
34 It is used as target if one generates the vo-dml/xml. from a UML/XMI representation.
36 All sub-folders of model/ SHOULD contain the vo-dml/xml representation generated from the XMI or written by hand.
37 All SHOULD contain an HTML documentation file named <dm.filename.prefix>.html derived from the vo-dml/xml file.
38 Most (all) contain a <dm.filename.prefix>.png file containing a diagram of the model derived from the vo-dml/xml file using GraphViz.
39 This image is used inside the HTML file.
41 IF one wants to generate the vo-dml/xml from an XMI version of the model, the vo-dml.properties file MUST contain
42 a 'xmi.source' property, which must give the name of the XMI file. This name is assumed to be relative to the folder.
43 Note, this name is NOT assumed to be named <dm.filename.prefix>.xml!
44 Some folders contain a ...-UML.png file. This is an image containing a diagram obtained from the
45 MagicDraw CE 12.1 tool with which the XMI file was created.
47 The vo-dml.properties file MAY define a property named 'html.preamble'. If this value is set it should identify a file containing
48 an HTML snippet (form TBD) that will be inserted at a certain part of the generated HTML documentation.
49 It allows some customization of the data model documentation. Was used by SimDM effort.
50 None of the current models have a preamble.
52 ./models/ivoa_wg.css
53 A CSS file used by generated HTML documents.
54 Put here in SVN so that a relative link can be given to it from the generated HTML.
56 ./models/xmi.css
57 A CSS file used by generated HTML documents.
58 Put here in SVN so that a relative link can be given to it from the generated HTML.
60 - ./models/ivoa
61 A special model containing definitions for most common primitive types as well as for quantity.
62 SHOULD be used by all other models as their main source for such primitive types.
64 - ./uml/
65 Contains a UML profile that should be used by all MagicDraw CE 12.1 UML representation in models/ if they should be compiled using the
66 xmi2vo-dml.xsl script.
68 - ./uml/IVOA UML Profile v-3.xml
69 A MagicDraw UML profile that can be used inside of a MagicDraw data model.
70 Best start for creating a new UML model that can be used as source for the xmi2vo-dml.xsl script
71 however is to use a template model in ./models/template
74 - ./xsd/
75 Contains XML schema and Schematron file defining the formal VO-DML/XML representation.
77 - ./xsd/vo-dml.xsd
78 Contains an XML schema defining the structure of the VO-DML representation of a data model.
80 - ./xsd/vo-dml.sch.xml
81 This file defines a Schematron schema containing validity rules that are hard or impossible to express in XML schema.
82 Used by the build.xml's 'validate_vo-dml' target.
84 - ./xsd/vo-dml-instance.xsd
85 Contains an XML schema defining the structure of basic instantiations of VO-DML data models.
87 - ./xsd/vo-dml.mapping.xsd
88 Contains an XML schema defining the structure of the mapping file used by XSLT processor and
89 various Java classes used for manipulating models and their instances.
93 - ./xslt/
94 This folder contains various XSLT scripts used in generating various artefacts.
96 - ./xslt/xmi2vo-dml_MD_CE_12.1.xsl
97 Contains XSLT that can generate a vo-dml representation from a properly defined UML model expressed in XMI.
98 It is shown to work with XMI generated using MagicDraw Community Edition 12.1.
99 Models defined in that tool MUST also use a particular UML "profile", defining stereotypes and tags for
100 adding more specific features to our model. A template UML diagram will be provided.
101 TODO The details of the MagicDraw modelling must be documented in (much) more detail.
102 For now you'd need assistance of Gerard Lemson or Laurent Bourges.
103 BUT note that it is NOT required to use UML, it is just one method to produce a vo-dml representation which is the
104 real core of the data model and the sole source of all further products.
106 Note. This script assigns a vodml-id to all model elements based on the XMI-id used for the element in the XMI model.
107 These are random strings, and have no structure. This script does NOT generate the more readable vodml-id values.
108 This script assigns this same ID string to the @id attribute of the <identifier> element containing the <vodml-id> element.
109 All <utype> elements will use this same string to identify the referenced <vodml-id>.
110 The more readable path expressions for the vodml-id elements is generated by the generate-utypes4vo-dml.xsl script.
111 See below how that works.
113 - ./xslt/xmi2vo-dml_Modelio_UML2.4.1.xsl
114 Script that generates vo-dml form UML created by Modelio when designed according to some pattern mimicking the profile
115 defined for MagicDraw. Seems to work (though not craegullt tested) for Mark's Modelio models for Cube/ImageDM.
117 - ./xslt/common.xsl
118 XSLT script containing some common templates used by other scripts.
120 - ./xslt/generate-utypes4vo-dml.xsl
121 XSLT script that generates human readable values for the <vodml-id> elements for a vo-dml diagram and updates <utype> values accordingly.
122 These follow the path syntax defined in appendix D of the VO-DMl spec, which itself is based on the UTYPE syntax proposed
123 in the SimDM model, and in the "original" UTYPEs document.
124 Its main role is to produce a human readable value that are guaranteed unique within the context of a <model> element.
125 This value is generated only for <vodml-id> elements that have an @id attribute that has the same value as the element itself.
126 This is to avoid updating <vodml-id> elements that have an explicitly defined value defined e.g. in the original UML/XMI model.
128 - ./xslt/utype.xsl
129 A utility XSLT script containing some templates used in generating utypes from the vo-dml rep.
132 - ./xslt/vo-dml2html.xsl
133 XSLT script that generates a default HMTL document from a vo-dml representation.
134 Is completely cross linked, contains all element (should at least).
135 Each element has an <a name="[utype]"> anchor in front of its definition.
136 This is assumed in the HTML generation when links to external models are created.
137 TODO expand on this description.
138 CAN include a table with possible paths. NOTE do not do that for STC!!!
140 - ./xslt/vo-dml2gvd.xsl
141 An XSLT script used to generate a so called GVD file that describe a model diagram from the vo-dml representation
142 accordiong to GraphViz GVD format.
143 This file is used by GraphViz to generate an image for the model.
144 It also (in the build.xml's run_vo-dml2gvd target) generates a map of the image
145 that is inserted into the HTML to create a cross linking between diagram and data model element in the HTML document.
147 - ./xslt/vo-dml2pojo.xsl
148 Generates "perfectly ordinary java" class definitions based on the models and the mapping_file.xml.
149 Have a deepToString method for serializing the objects to an XML format compatible with ./xsd/vo-dml-instance.xml.
150 Have generic property getters and setters ...
151 TBC
153 - HOW TO compile.
154 Need to generate java code for ivoa model, move this to source before calling ant compile, as custom java/src classes need it.
156 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
157 +++++++++++++ How to use build.xml and description of its targets +++++++++++++
158 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
159 1. check out complete vo-dml project from SVN. URL = https://volute.googlecode.com/svn/trunk/projects/dm/vo-dml/
160 2. ensure one has ant installed. versions tested are 1.8, 1.9
161 3. configure build.properties file according to description in SVN version.
162 4. if one has an XMI file built according ot one of the supported profiles (MD_CE_12.1 or Modelio_UML2.4.1),
163 run the corresponding run_xmi2vo-dml_[XMI-spec] target.
164 5. run run_vo-dml2html to generate HTML documentation.
165 6. run run_vo-dml2pojo to generate Java classes. Needs properly defined mapping file, see example in
166 https://volute.googlecode.com/svn/trunk/projects/dm/vo-dml/java/gen/mapping_file.xml
167 7. especially when written by hand, vo-dml files should be validated.
168 Target run_validate_vo-dml does so. Will indicate XSD violations in console,
169 will write schematron rule violations in file indicated by console massage.

ViewVC Help
Powered by ViewVC 1.1.26