This page details five things:
JDOM is fully functional on Android. This is 'tecnhically' true. Android itself is signifcantly limited though in the following areas:
Drop the JDOM 'core' jar in your
libs folder in your Android project folder. You may need to create the
libs folder if you do not already have it (note, it is the
libs folder with an 's', not
The following should be considered:
StAX related functionality: Android uses a different type of 'Pull-parsing' - search for 'Android XML Pull Parser'. JDOM is not compatible with this parser, and given that the parser is not implemented in regular Java, it will not happen. Further, Android makes it intentionally difficult to implement new classes in the 'java*' packages, so it is essentially impractical to add the API's necessary to include StAX parsing.
Apart from StAX, everything else in JDOM works! That's the good news, but it comes with one big BUT:
JDOM relies on a third-party parser to load XML documents and to validate the input, and the default Android parser is different to the standard Java parser, and it is also different to Xerces. As a consequence, there are a number of JDOM test cases that fail on Android, but these are not the fault of JDOM, but rather they are limitations of Android. See the next section for a description of these issues.
The big issue is the lack of a complete XML parser on Android. The default Android parser has significant limitations, and these limitations are apparent. It is possible to override the default parser, but in the long run that does not help much. Still, it makes sense to do two things: list the issues with the default Android parser; and show how to install a 'third party' parser, even though it will not all work...
Here is a full breakdown of the failing JUnit test cases when run on Android.
The following issues are notable on the standard XML Parser in Android:
org.xml.sax.ext.DeclHandlerspecification). The most significant issue related to this is that JDOM is not able to output the file with the same information as the source.
The issues related to the XMLSchema are considerable. Of importance are:
XMLReaders.DTDVALIDATINGwill cause a JDOMException if you try to use it.
XMLReaders.XSDVALIDATINGwill cause a JDOMException if you try to use it.
XMLReaderXSDFactorywill throw JDOMException from the constructor.
It is logical to consider Xerces as the third-party parser, but this issue is complicated enough to require it's own page... Xerces on Android. Note: Using Xerces Does Not Solve All These Issues - it causes an adroid application crash!
Android has a few built-in mechanisms for testing code. The most rigorous mechanism is to actually run the full JDOM test harness on an (emulated) Android device. There are a few challenges with this approach and it is valuable to document how the actual tests are run (these are 'logistics issues' purely related to getting the test infrastructure running):
Android testing is set up with two Android projects. The first project is the 'real' project, and the second project is the 'Test' project. The two projects are linked using Android project references. You build the two projects in to seperate android 'apps', and then install both apps on to the Android device. After they are installed, you then run the tests on the device. The test results are returned to the 'calling' process.
A special note must be made about 'resources'. 'Resource' has a number of meanings in Java and Android. In Android, a resource is a special construct that is available as a special static class called 'R'. JDOM uses a different type of resource accessed through
ClassLoader.getSystemResource(...), and the
ClassLoader.getSystemResource(...) type methods are completely unreliable on Android. After a lot of back-and-forth, including using custom on-load procedures to move Android 'assets' to the 'cache' filesystem, it was discovered that the
this.getClass().getResource(...) method is reliable on both Android and Java... see ClassLoader.getSystemResource().
There are some significant logistical problems with setting up the JDOM tests in such an environment:
All these requirements have been met in a way that makes it almost easy.... ;-)
The testing process has been almost entirely automated now. In essence, if you want to run the tests yourself, you need to:
<AndroidDirectory>/toolsto your PATH
C:\jdomfor windows, or
android create project --target android-15 --name JUT --path ./JUT --activity JUTActivity --package org.jdom2
android create test-project -m ../JUT -n JUTTest -p JUTTest
git clone git://github.com/hunterhacker/jdom.git
ant android -Dandroid=../ -Dandroid.project=JUT -Dversion=2.android
This is the part that interfaces the JDOM project with Android. It does the following:
Note: a conversion layer is created to translate the JUnit4 tests in JDOM to JUnit3 tests in Android. This layer essentially wraps each JUnit4 test in whatever means necessary to make it behave as if it was called from a JUnit4 TestRunner. You can inspect the generated JUnit3 source code in the test Android project. The program that does this conversion is included in the JDOM contrib section:
As this testing process was built, a number of technical issues in both Android and JDOM became apparent. Each of these issues could be called a 'bug' in JDOM's run-anywhere status. The following JDOM issues have been resolved:
Android also has some issues:
Now that we actually have JUnit tests running on android, we can analyze the results.
Android ships with its own XML Parser. JDOM typically recommends using the Xerces parsers, and the JDOM tests are all written to pass when using Xerces. Android does not use the Xerces parse, and some differences are a result of that. It is thus useful to document what does not work with the Android built-in XML parser.
The StAX test code simply cannot run on Android. The core StAX Libraries are not available. The StAX tests cause the Android test project fail to compile (the tests throw XMLStreamException which is not available). As a result, the StAX tests are not even generated.
Xerces SAX Parser provides any internal subset data from the DocType as part of the SAX Build process. The Android SAX parser does not. This is causing about a dozen tests to fail. This issue is not critical though, I don't think.
The Android parser ignores the feature to turn off entity expansion (expand-general-entities). As a consequence, the Unit tests that expect to parse a document and get a JDOM EntityRef in the results are going to fail.