/**
Copyright 2004 Arnaud CEOL

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

 You may obtain a copy of the License at
 http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 
*/

for more information, see doc/documentation.html
contact me for any question or suggestion at [email protected]

NAME 

XML Maker, XML flattener

SYNOPSIS 

Linux:

    * Flattener without Graphical User Interface (GUI):

      sh bin/xmlflattener -mapping <mapping-file.xml>  -xmlDocument <your PSI1.0 XML document> -o <output file>


    * Flattener with GUI:

      sh bin/xmlflattener-gui


    * Maker without Graphical User Interface:

      sh bin/xmlmaker -mapping <mapping-file.xml>   -o <output xmlDocument>  -dictionaries <dictionaries>  -flatfiles <flat files>


    * Maker with Graphical User Interface:

      sh bin/xmlmaker-gui

windows:

    * Flattener without Graphical User Interface (GUI):

      bin/xmlflattener.bat -mapping <mapping-file.xml>  -xmlDocument <your PSI1.0 XML document> -o <output file>


    * Flattener with GUI:

      bin/xmlflattener-gui.bat


    * Maker without Graphical User Interface:

      bin/xmlmaker -mapping <mapping-file.xml>   -o <output xmlDocument>  -dictionaries <dictionaries>  -flatfiles <flat files>


    * Maker without Graphical User Interface:

      bin/xmlmaker-gui.bat




DESCRIPTION 
XML Maker and XML Flattener are two applications that allow to convert tab delimited files to XML documents and XML documents to tabdelimited files according to an XML schema.

Both application can be used either with or without graphical interface. The graphical interface allows to load an XML schema and to create a mapping between 
flat (tab delimited) files and XML document. Once a mapping has been created, it can be reused directly on the command line.

Flattener:
To create a mapping file, an XML schema should first be loaded in the GUI . A graphical tree representation of this schema is then created. 
On this tree it is possible first to choose the 'main node', i.e. the node that contains all information that will be displayed on a single 
line of the output tab-delimited file. Then it is possible to select the elements and attributes that will be exported.
The application will automaticaly calculate the number of columns necessary according to the number of sub-elements found.

Maker:
To create a mapping file, an XML schema should first be loaded in the GUI, then one (or more) flat file. A graphical tree representation of this schema is created. 
On this tree it is possible first to associate a node to a flat file. An element corresponding to this node will be created in the output XML document 
for each line of the flat file. At this point the fields of the file can be associated to the nodes of the schema.
Other types of associations are possible:
* to default value: specify the value that will be always associated to this node, whatever the flat files contains
* to automatic value: a unique value will be automaticaly generated
* to dictionary: a dictionary is a tab delimited file that contains synonyms of terms. It is possible to associate a node to which has already been 
assigned a value (association to field, default value), to a dictionary. When a synonym is found, it will be replace by its main value.

Both applications have been develop on and require a Java 1.4 environment (or newer) (http://www.java.com/en/download/index.jsp).


OPTIONS

Flattener (without GUI):

    * -mapping <mapping_file>: the mapping file
    * -xmlDocument <document.xml>>: the XML document to parse
    * -o: name of the output file
    * -validate (no argument): the XML document should be validated. Validation is required to retrieve automatically XML ids, used for instance in PSI-MI XML 1.0 normalized documents. Validation may be slow and it is recommended to not use when not needed (not needed for PSI unnormalized or PSI-MI 2.5).

Maker (without GUI):

    * -mapping <mapping_file>: the mapping file
    * -o <xmlDocument>: name of the output XML document
    * -dictionaries <dictionaries> : names of the dictionary files in the right order, separated by comma
    * -flatfiles <flat files> : names of the flat files in the right order, separated by comma



ENVIRONMENT 
The applications often require extra memory allocation. You can specified how much memory has to be reserved 
by java with  -Xms  and -Xmx options, for instance
java -Xms256M -Xmx512M 

FILES

Some files are available in the data directory. those files are relative to the Protein Standard Initiative (http://psidev.sourceforge.net/)
for which this software has been created.
mif.xsd, MIF2.5.xsd : PSI standard schema (version 1.0 and 2.5)
However, for the latest PSI schema files always refer to 
http://psidev.sf.net/mi

flattener-mapping-psi10.xml, flattener-mapping-psi25.xml, maker-mapping-psi10.xml, maker-mapping-psi25.xml:
	examples of mapping files for both applications
	
psimaker-template.txt: template flat file that can be used with the XML Maker application and its respective mapping files.
psimaker-example.txt: an example  (one line) of use of this template.


EXAMPLES (Linux)

    * PSI 1.0 flattener:

      sh bin/xmlflattener -mapping data/flattener-mapping-psi10.xml  -xmlDocument <your PSI1.0 XML document> -o <output file>

    * PSI 2.5 flattener:

      sh bin/xmlflattener -mapping data/flattener-mapping-psi25.xml  -xmlDocument <your PSI2.5 XML document> -o <output file>

    * PSI 1.0 maker:

      sh bin/xmlmaker  -mapping data/maker-mapping-psi10.xml -flatfiles <your flat file>  -xmlDocument <your PSI2.5 XML document> -o <output XML document>

    * PSI 2.5 maker:

      sh bin/xmlmaker -mapping data/maker-mapping-psi25.xml -flatfiles <your flat file>  -xmlDocument <your PSI2.5 XML document> -o <output XML document>



SOURCE:
all sources of this software are available in the src directory

INSTALLATION:
you can build the software using maven (http://maven.apache.org):
mvn clean install appassembler:assemble assembly:assembly
classes will be compiled into the target/classes directory, a jar file will be added to the target directory. A compressed (zip) 
package containing automatically generated scripts and libraries is also added to the target directory.


SEE-ALSO
This software has been developed for the HUPO Proteomics Standards Initiative (http://psidev.sourceforge.net/).