Troubleshooting

The Android-PList-Parser is designed to work with valid PList XMLs only. Before you start getting into the code, you want to be certain that the PList XML you're working with is valid according to the DTD (check readme and code for DTD URL). If it's valid, proceed to the next paragraph. If it's not valid according to the DTD, your task has changed from 'troubleshooting' to 'modifying'. Depending on the degree of non-conformance, you may want to write code from scratch instead of trying to modify this code (since it's algorithm relies on the assumption of validity). This code's license lets you borrow from it freely as long as you place credits.

If the parser isn't working with valid PList XML you'll want to start troubleshooting at the unit-test level. You should be able to easily follow the pattern in PListXMLParserTest.java to add test cases for your specific PList structure. You can then set debugging breakpoints and/or add logging to dig into the code and find a fix.

If you're using the code you probably already have an Android development environment setup (which is no brief task). Running the tests is easiest from Eclipse, but the Android emulator is slow. To improve overall development time, try running the test(s) on a device attached via USB if you have one available. If you can deploy the debug build (the typical build generated in Eclipse, using the 'debug key') to the device, you can set breakpoints against it. If you don't have a device, enable AVD snapshots to improve emulator start-up time. If you do this, it's recommended that you launch the emulator the first time and close it once it's started - then open it again and disable shapshots. AVD snapshots are saved when the emulator closes so if you leave them enabled the time-saving is scant.

The parser's SAX handler should be reasonably commented to follow along with. However, it's logic isn't necessarily trivial to understand and modify. The basic rule for the algorithm is that elements are treated in two different ways: ones that can have children (Dict and Array), and ones that can't. Elements that can have children are pushed onto a stack - and an interesting pop/re-push method is used to attach children to their parents. With these concepts in mind, reading the code should be a little easier.

Please consider contributing a fix back to the project if you've added a test case and discovered a bug. We'd love to have a pull request from you and get your contribution into the mainline.

NOTE: PListXMLHandlerTest.java is somewhat of a mess right now. The parser has seen major refactoring and PListXMLHandlerTest's requirement for object mocking has taken a backseat to the value of focusing on PListXMLParserTest.