mmbase logo

Quickstart Installation Guide

Documentation

How to install XML Importer

How to run the examples

How to de-install the examples

MMBase

home

Quickstart Installation Guide

Author: Rob van Maris
Date: 2004-11-04

This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative.

The license (Mozilla version 1.0) can be read at the MMBase site. See http://www.mmbase.org/license

Table of Contents

1. Documentation
2. How to install XML Importer
3. How to run the examples
4. How to de-install the examples

1. Documentation

For a full understanding of the XML Importer, it is recommended to read the following documents, available on the MMBase website

  1. TCP 1.0 documentation (see Temporary Cloud Project).
  2. XML Importer overview (see XML Importer Project).
  3. The javadoc documentation of the org.mmbase.applications.xmlimporter package.

2. How to install XML Importer

The XML Importer has been tested with the recent CVS versions of MMBase. If you downloaded the MMDistro you have to update some files from cvs and copy them to your source directory. In our case these were:

Since MMBase is improved all the time this list will grow with time. If compilation errors occur a cvs update might solve the problem.

Next:

  1. Download and unzip xmlimporter.zip from the XML-importer homepage on the MMBase website.
  2. Update the contents of mmbase/applications/xmlimporter from cvs.
  3. Update the contents of html/mmapps/xmlimporter from cvs.
  4. Update the file config/default/dtd/transactions.dtd from cvs.
  5. Edit transactionhandler.xml in your MMBase modules config directory, so that its status is set to "active" and its classfile to "org.mmbase.applications.xmlimporter.TransactionHandler".
  6. Copy upload.jar from /lib to your MMBase lib directory (usually Web-Inf/lib in your web-app). It is solely used for the file upload by the XML importer user interface JSP.
  7. In your MMBase config directory, create directories "import" and "import/report".
  8. Recompile/rebuild and redeploy your MMBase binaries.

The next time MMBase is started, XML Importer will be installed and fully functional. It is recommended to install the examples next.

3. How to run the examples

It is recommended to execute the JUnit tests as the first step, to see if everything works as expected.

  1. Configure log4j to see the results of the JUnit tests, by setting the priority for the category org.mmbase.applications.xmlimporter.junit.TestRunner to "service".
  2. Restart MMBase. The junittester module is configured to execute two testsuites when MMBase is initialized: TmpObjectTest, TransactionHanlderTest and SpecificObjectFinderTest.
  3. Look in the log4j logfile to see the result of the tests. If all went well, the TestRunner reports having finished both testsuites with result OK. If you see the lines >OK (6 tests), OK (5 tests) and OK (1 tests) XML Importer is running as expected (in spite of some warnings you may get), otherwise something is wrong.

If the TestRunner reports errors or failures, set logging priority to "trace" for the category org.mmbase.applications.xmlimporter and restart MMBase to get a more detailed report to see what went wrong. Don't proceed until the problem is fixed and all tests are successfull.

If you don't need the junittester anymore, set its status to "inactive" in its configuration file "junittester.xml".

The next examples will demonstrate the XML importer with the JSP user interface. It uses 3 XML files with XML Importer commands. In order to understand these, you must have read the XML Importer documentation.

  1. In a browser, go to http://localhost/mmapps/xmlimporter/jsp/importhome.jsp.
  2. Use the "Browse..." buttons to select the files "transaction1.xml", "transaction2.xml" and "transaction3.xml" in the /demo directory of the unzipped file. These are the XML files to be processed by the XML importer.
  3. Press "Start Upload", this will upload the files to a webserver directory ("import" in your MMBase config directory).
  4. Press "Back to import page" to return to the importer homepage.
  5. Now you can select one of the uploaded files under "Start Import". Select "transaction1.xml" and press "Start Import" to process that file.

  6. Description of transaction1.xml:

    This transaction creates new objects: 1 movie and 3 related persons - of which 2 are identical. These are then merged based on an exact match of persons and movies. Note that:

    • When this transaction is repeated it will not create new objects, because the objects are already present in the persistent cloud.
    • The two identical persons are merged and result in a single persons object.
  7. The next html-pages will inform you when the XML importer has finished, also telling "NO DUPLICATES FOUND", meaning there were no problems (see below). Go to the MMBase editors for personsxxx and moviesxxx to see the resulting objects.
  8. From to the importer homepage import "transaction2.xml" in the same way.

  9. Desciption of transactions2.xml:

    This transaction creates new objects:1 movie and 1 related person. These are then merged based on an exact match of persons and movies. Note that:

    • Since the persons merge is based on an exact match of fullnames, "Erik Visser" and "Eric Visser" are considered different persons.
    • Since the movies merge is based on an exact match of titles, "Finalist the Movie" and "Finalist the Movie II" are considered different movies.
  10. The next html-pages will inform you when the XML importer has finished, also telling "NO DUPLICATES FOUND", meaning there were no problems. Go to the MMBase editors for personsxxx and moviesxxx to see the resulting objects.
  11. Repeat the import of either transaction1.xml or transaction2.xml. This time, no objects will be created, since they are already present.
  12. From the importer homepage import "transaction3.xml" in the same way.

  13. Description of transactions3.xml:

    This transaction creates new objects:1 movie and 1 related person. These are then merged based on a fuzzy match of persons (90%) and movies (95%). Note that:

    • Since the merge is based on a fuzzy (90%) match of fullnames, "Erik Visser", "Eric Visser" and "Erie Visser" are considered the same person, so there will be ambiguity when merging the persons.
    • Since the movies merge is based on a fuzzy (95%) match of titles, "Finalist the Movie II" and "Finalist the Movie III" are considered the same movie, and "Finalist the Movie" is considerd a different movie, so there is no ambiguity when merging the movies.
  14. The next html-pages will inform you when the XML importer has finished, but this time with the following message: "DUPLICATES FOUND". This means there was a transaction that could not be committed because an ambiguity arose while looking for similar objects.
  15. Take a look at the file "import\report\tcpReport.txt" in your MMBase config directory, to see which transaction was not committed and what the problem was. (You can set the name of the reportFile by setting the reportFile attribute of the transactions element.)
  16. Repeat the import of transactions3.xml, but this time be sure to check the "process duplicates interactive" checkbox.
  17. In the interactive mode, the XML importer will consult you as soon as it runs into ambiguity because of duplicates. It will show you the original (input) object, and the objects resulting from merging it with the different candidates. Choose the mergeresult with fullname "Erik Visser" by pressing the button beneath it.
  18. Go to the MMBase editors to see the resulting objects. In this case both the movie and person are merged with existing objects, but a new relation is added, since this relation was not present already.
  19. Finally, return to the importer homepage, and use third section to delete the uploaded files from the server.

4. How to de-install the examples

Reverse the steps in the examples installation guide to de-install the examples.

This is part of the MMBase documentation.

For questions and remarks about this documentation mail to: documentation@mmbase.org