Sunday, January 07, 2007

Annotations (Metainfo)

Many APIs require a fair amount of boilerplate code. For example, in order to write a JAX-RPC web service, you must provide a paired interface and implementation. This boilerplate could be generated automatically by a tool if the program were “decorated” with annotations indicating which methods were remotely accessible.

Other APIs require “side files” to be maintained in parallel with programs. For example JavaBeans requires a BeanInfo class to be maintained in parallel with a bean, and Enterprise JavaBeans (EJB) requires a deployment descriptor. It would be more convenient and less error-prone if the information in these side files were maintained as annotations in the program itself.

The Java platform has always had various ad hoc annotation mechanisms. For example the transient modifier is an ad hoc annotation indicating that a field should be ignored by the serialization subsystem, and the @deprecated javadoc tag is an ad hoc annotation indicating that the method should no longer be used. As of release 5.0, the platform has a general purpose annotation (also known as metadata) facility that permits you to define and use your own annotation types. The facility consists of a syntax for declaring annotation types, a syntax for annotating declarations, APIs for reading annotations, a class file representation for annotations, and an annotation processing tool.

Annotations do not directly affect program semantics, but they do affect the way programs are treated by tools and libraries, which can in turn affect the semantics of the running program. Annotations can be read from source files, class files, or reflectively at run time.

Annotations complement javadoc tags. In general, if the markup is intended to affect or produce documentation, it should probably be a javadoc tag; otherwise, it should be an annotation.

Typical application programmers will never have to define an annotation type, but it is not hard to do so. Annotation type declarations are similar to normal interface declarations. An at-sign (@) precedes the interface keyword. Each method declaration defines an element of the annotation type. Method declarations must not have any parameters or a throws clause. Return types are restricted to primitives, String, Class, enums, annotations, and arrays of the preceding types. Methods can have default values. Here is an example annotation type declaration:

/**
* Describes the Request-For-Enhancement(RFE) that led
* to the presence of the annotated API element.
*/
public @interface RequestForEnhancement {
int id();
String synopsis();
String engineer() default "[unassigned]";
String date(); default "[unimplemented]";
}

Once an annotation type is defined, you can use it to annotate declarations. An annotation is a special kind of modifier, and can be used anywhere that other modifiers (such as public, static, or final) can be used. By convention, annotations precede other modifiers. Annotations consist of an at-sign (@) followed by an annotation type and a parenthesized list of element-value pairs. The values must be compile-time constants. Here is a method declaration with an annotation corresponding to the annotation type declared above:

@RequestForEnhancement(
id = 2868724,
synopsis = "Enable time-travel",
engineer = "Mr. Peabody",
date = "4/1/3007"
)
public static void travelThroughTime(Date destination) { ... }
An annotation type with no elements is termed a marker annotation type, for example:
/**
* Indicates that the specification of the annotated API element
* is preliminary and subject to change.
*/
public @interface Preliminary { }
It is permissible to omit the parentheses in marker annotations, as shown below:
@Preliminary public class TimeTravel { ... }
In annotations with a single element, the element should be named value, as shown below:
/**
* Associates a copyright notice with the annotated API element.
*/
public @interface Copyright {
String value();
}
It is permissible to omit the element name and equals sign (=) in a single-element annotation whose element name is value, as shown below:
@Copyright("2002 Yoyodyne Propulsion Systems")
public class OscillationOverthruster { ... }
To tie it all together, we'll build a simple annotation-based test framework. First we need a marker annotation type to indicate that a method is a test method, and should be run by the testing tool:
import java.lang.annotation.*;

/**
* Indicates that the annotated method is a test method.
* This annotation should be used only on parameterless static methods.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Test { }
Note that the annotation type declaration is itself annotated. Such annotations are called meta-annotations. The first (@Retention(RetentionPolicy.RUNTIME)) indicates that annotations with this type are to be retained by the VM so they can be read reflectively at run-time. The second (@Target(ElementType.METHOD)) indicates that this annotation type can be used to annotate only method declarations.

Here is a sample program, some of whose methods are annotated with the above interface:

public class Foo {
@Test public static void m1() { }
public static void m2() { }
@Test public static void m3() {
throw new RuntimeException("Boom");
}
public static void m4() { }
@Test public static void m5() { }
public static void m6() { }
@Test public static void m7() {
throw new RuntimeException("Crash");
}
public static void m8() { }
}
Here is the testing tool:
import java.lang.reflect.*;

public class RunTests {
public static void main(String[] args) throws Exception {
int passed = 0, failed = 0;
for (Method m : Class.forName(args[0]).getMethods()) {
if (m.isAnnotationPresent(Test.class)) {
try {
m.invoke(null);
passed++;
} catch (Throwable ex) {
System.out.printf("Test %s failed: %s %n", m, ex.getCause());
failed++;
}
}
}
System.out.printf("Passed: %d, Failed %d%n", passed, failed);
}
}
The tool takes a class name as a command line argument and iterates over all the methods of the named class attempting to invoke each method that is annotated with the Test annotation type (defined above). The reflective query to find out if a method has a Test annotation is highlighted in green. If a test method invocation throws an exception, the test is deemed to have failed, and a failure report is printed. Finally, a summary is printed showing the number of tests that passed and failed. Here is how it looks when you run the testing tool on the Foo program (above):
$ java RunTests Foo
Test public static void Foo.m3() failed: java.lang.RuntimeException: Boom
Test public static void Foo.m7() failed: java.lang.RuntimeException: Crash
Passed: 2, Failed 2
While this testing tool is clearly a toy, it demonstrates the power of annotations and could easily be extended to overcome its limitations.

Thursday, January 04, 2007

The Java performance debate

  1. Java is slow
  2. Java is a memory hog

The corollary being that Java on the desktop is infeasible for those without the patience of a saint. Funnily enough, in my experience, many people who have commented to me, "Andy, I don't like Java because it's slow" are the very same people who use Perl/Python/PHP. It suggests to me that not all the criticism is entirely objective! This article aims to discuss some of the criticisms aimed at Java and see whether they are justified.

Memory

To be honest, even the most faithful Java evangelist would have trouble believing that Java is light on memory usage (relatively speaking, of course). I don't believe that it is, so I'm not going to pretend. Object-orientated languages typically have a slightly larger memory footprint as you have to carry around a lot of information about all your objects currently initialised. A large factor is simply the JVM itself. A simple "Hello world!" class of say a kilobyte will still require the entire JVM, and the several megabytes that entails. Yet, you must think about what you get for your money, so to speak. The JVM and the Java runtime classes are feature packed.

However, one man's feature is another man's bloat and I suppose this is where a lot of the debate stems from. When designing languages, you go either minimalist, and rely on the users to implement all the functionality they need; or you go for the opposite, and provide an extremely rich language where developers can rapidly produce software. As a Java developer, I don't need to manage my memory programmatically: I can leave it all to the garbage collector. This is great for me, but not necessarily the most efficient way to manage memory. If you want to partake in old-school manual memory-management then you can do a certain amount (such as dereferencing your objects and then explicitly calling the garbage collector), but nothing as low-level as what C programmers would be accustomed to. There are other things you can do as a Java programmer to reduce the overhead such as using third-party libraries designed to be more efficient, such as fastutil or Javolution, which replace commonly used classes like the collections framework.

It's worth being aware that the JVM by default doesn't use all the available memory on a given system. This means that by default a Java application won't overwhelm your system and cause heavy swapping and other such nastiness. Programs known to be memory intensive by nature, like scientific applications can in fact be limited by the JVMs conservative usage, and so many developers launch their Java apps with special JVM flags that permit Java to utilise additional memory.

Speed

To be fair, before I began looking into this, I had never thought that Java was the fastest language out there. I suppose, however, that because I'm still using Java, that I believe it's fast enough. Assuming that C++ is the holy-grail in terms of performance because it's so fast, then even if Java could achieve half it's speed, it's still fast! People seem to get so focussed on the milliseconds that they forget that if a task takes 0.01s in C++ and 0.02s in Java, then, "oh no", it's half as slow!

Yet, since mulling over this topic, I have found interestingly that Java has really made great gains in overall performance that can in fact put it on par with C++, if not a little quicker! There are various benchmarks that have reported Java algorithms running quicker than C++ equivalents. (Java Pulling Ahead, Java Faster than C++, FreeTTS case study) You will of course find many benchmarks finding the converse. What this shows is that they're at least comparable which is enough for me to imply that Java is fast, and I'll leave it to the benchmark zealots to fight over their nanoseconds.

I think Java is somehow still seen as an interpreted language; in fact, it does get compiled to native code using Just In Time (JIT) compilation. It is also a myth to think that JIT code is slower than pre-compiled code. The only difference is that bytecode gets JITed once its required (i.e., the first time a method is called - and the time is negligible) it then gets cached for subsequent calls. JIT code can benefit from all the same optimisations that pre-compiled can get, plus some more (from Lewis and Neumann, 2004):

  • The compiler knows what processor it is running on, and can generate code specifically for that processor. It knows whether (for example) the processor is a PIII or P4, if SSE2 is present, and how big the caches are. A pre-compiler on the other hand has to target the least-common-denominator processor, at least in the case of commercial software.
  • Because the compiler knows which classes are actually loaded and being called, it knows which methods can be de-virtualized and inlined. (Remarkably, modern Java compilers also know how to "uncompile" inlined calls in the case where an overriding method is loaded after the JIT compilation happens.)
  • A dynamic compiler may also get the branch prediction hints right more often than a static compiler.

Even if it were slower, once again, you have to think what value for money you get per-clock cycle with Java. Many of the core classes are thread-safe as standard, for example; and let's not forget free garbage collection. Also, that bit of code will run fine on all supported platforms without any additional effort. All the OS abstraction is done for you. That's pretty incredible when you think about what it takes to actually pull off such a large abstraction layer like that.

Java Virtual Machine

The JVM once again causes controversy when evaluating Java's speed. Java benchmarks typically discount the startup time of the JVM itself. Non-Java benchmarkers would consider this unfair, and not fully representative of the overall program performance. It's a difficult debate. If I want to simply compare, say, raw Java Vector performance versus raw C++ STL vector performance, then why should we consider start-up times? Also, if I'm trying to profile algorithms within my program, again, why should start-up be useful in evaluating? But, if I'm comparing two programs that perform an equivalent task, I'd probably want to consider the overall time from initial execution to completion. Having said that, the larger the application, the less of an issue the JVM load times will be due to economies of scale. (Note, even this is getting better thanks to Class Data Sharing, amongst other things) One other thing to remember is that many Java applications are actually deployed as a Jar file (a glorified Zip file, essentially). You can execute the code within from the JVM directly - it therefore has to decompress the file first, and this obviously incurs a time penalty.

The Project Barcelona research group at Sun are coming up with some interesting technologies to improve the JVM in the future. That's not to say that the current JVM hasn't been improving steadily during each release. The Multi-tasking Virtual Machine (MVM) looks most promising as it'll allow multiple Java applications to share the VM, reducing the overall burden on system resources. Ok, I know you can do this already on the current JVM, but it's still a little raw. The MVM will be much more scalable and efficient. It seems to me that with such a system, you can finally run the JVM as a daemon on your system at startup, and then all subsequent Java programs you load will load as quickly as native apps. One can't help but lose some optimism when you learn that the MVM may not even make it into Java 1.7 (Dolphin) due in the second half of 2007. I hope it does! In the meantime, you could to better than to look at some of the existing shared VMs like Janos, JKernel and Alta.

Java desktop

It's on the desktop where many people form their opinions of Java, and it is here where people complain most about performance issues. The Swing toolkit is very powerful and rich, yet it is huge. Werner Randelshofer states that a Swing "Hello world!" program will require approximately 800 classes to be initialised before the user sees the infamous greeting. Yet, there is no shortage of Java developers who will tell you that Swing is fast.

Perceived performance

What those in the know will tell you is that Java in fact has a problem in perceived performance. You often hear about grey rectangles, unresponsive widgets, etc. The issue here is that Swing is perfectly responsive, until you hit a widget that triggers a task. The biggest trap Swing programmers fall into is that they don't understand the threading model that is employed.

Here's the science...

The Java designers decided not to make Swing components thread-safe, and instead opted for a single thread (known as the event-dispatch thread), to maintain the state of the GUI components. Therefore, your code that you want to run when a user clicks on a given button by default gets added to the EDT. If the code is something non-trivial, like loading a large file or querying a database, then this will block the EDT until it completes, resulting in an unresponsive GUI in the meantime. The remedy is to dispatch long tasks (i.e., anything likely to take > 0.25s) on their own thread, which frees up the EDT for doing purely GUI related tasks (see Ben Galbraith's excellent tutorial).

The EDT approach is hardly exclusive to Java because it makes toolkit design much easier. You'll find .Net's Winforms opts for a similar model. The EDT is supposed to simplify things, yet it seems to be a common pitfall. Some one commented recently:

"... I may point out that Swing is not slow... The problem is that's very easy to shoot yourself in the foot with Swing, but can happen with any toolkit, even those using native code. Well written Swing code can be as fast as a native application, if not faster."

Shooting yourself in the foot

I was interested in this comment and decided to go off at a bit of a tangent here to examine if Java is really that prone to making unresponsive interfaces. I was discussing this with Jasper Potts from Xerto (producer of the visually impressive Java app, Imagery) and we got on to documentation:

"Swing itself is not slow, but that's not to say that it's that easy to write large applications that perform well. There is definitely room for some more articles on using Swing in the desktop... There is a real need for Swing books that tell you how to do things in the real world. [Desktop Java Live] is the first book I have come across that is trying to do that. Even all the books called "Advanced ...","Extreme...", etc., all they do is redo the Java [API] docs for the more advanced components. There are a few topics that just don't seem to be documented at all well anywhere like the Focus System."

Scott Delap, author of Desktop Java Live indulged me an a discussion on this topic too:

"Java/Swing being slow is one of those myths that has become embedded in the mindset of developers. I can easily write a desktop application in any language that is slow. I would suspect that 8 out of 10 developers that comment "Swing is slow" haven't written a Swing app in at least 5 years. It is much like the Linux developer community labelling Microsoft as evil. Even if Microsoft became the best open source citizen tomorrow, it would take many years before the majority of developers would have this opinion of them. As far as countering the statement, I think the best rebuttal is the continuing production of quality desktop applications written in Java. The more there are the harder it is to argue against them."

DJL devotes an entire chapter to threading in Swing. I asked Scott whether he thought threading was a common pitfall for Java Swing developers and therefore was it something inherently wrong with Java's design:

"Anyone that is a software developer gets paid for a reason. Software development isn't something that you can master in a three day correspondence course. I've always felt that it is each developer's responsibility to become competent with the features of the language/toolkit they are developing with. Threading is a core part of writing desktop applications. You can easily find discussions about desktop threading on the Internet in regards to numerous other toolkits. It makes no sense to me when people complain about threading in respect to a language. No one complains they have to learn OO to use Java or for-loops to use .NET effectively. In regards to Swing specifically, it is designed very similarly to other common UI toolkits. If you look at QT, GTK, SWT, .NET, etc., you will see they all use some variation on the single event thread concept. Some have the concept of a global lock, however I'd much rather have the ability to address such complexities myself than a brute force approach supplied for me. I will concede that a few more threading utilities built into the core of Swing might help new developers. However, open source projects such as Foxtrot, Spin, and SwingWorker address a large portion of Swing threading related issues. Relating back to my earlier point, I think it is the responsibility of good developers to become aware of the tools that can enhance their development process."

An interesting point here is that other UI toolkits use this threading model, but you rarely hear that these toolkits are slow. Yet, I have seen examples for most which also block the thread and therefore become unresponsive. I think Java has had some bad luck in that its legacy has stuck. Nowadays though, I do believe that if you see a slow Java application, the fault lies at the developer's door, and not Java. For example, Eclipse had recently come under fire for becoming slow - especially with its start up. Critics automatically assume that this is because of Java. In its most recent M7 milestone release they significantly improved performance - a bottleneck being the plugin framework that Eclipse relies not being very scalable for increased numbers of plugins. The point being that this is an algorithmic issue - one that could have occurred in any language, yet it seems to become a Java issue. Of course, some more prominent articles and examples covering common pitfalls would certainly help to ensure new UI programmers get good performance from the outset.

Java2D

Some other performance issues have been down to the underlying graphics framework, Java2D. Because Swing components are all emulated, they are very much at the mercy of Java2D. Fortunately, this package is extremely competent in features, and by virtue of being graphics orientated, very quick too (i.e., performance of any graphics framework is a core priority, and Java2D is no different). However, the Java2D have been working hard recently to improve several aspects that should enhance this even further. One area is the use of hardware acceleration where possible. This must be a nightmare to implement in a multi-platform fashion, but it's being done, slowly but surely. I hate to say it, but Microsoft has made this easier for the Windows platform due to its DirectX graphics abstraction layer. Windows users can expect to see this pipeline utilised even more in future releases. The OpenGL pipeline is also being advanced significantly which will benefit all platforms (currently, support is disabled by default but can be switched on; this will be enabled in the next release.)

There are also a few little tweaks for Mustang that will even help in the "perceived" performance problems. For example, the abolition of the infamous "grey rect" problem. The fix required the use of true double-buffering support for Swing, which is another great boost for the toolkit.

Will someone please think of the users?!

As a Java developer, I will happily sacrifice some memory, and a bit of speed, because the Java platform affords many other benefits. I find myself being productive with Java because of its richness and ease of use. I do benefit from the multi-platform aspect too, because I use Linux to develop yet many of my typical users are on Windows.

However, the argument is that a potential end-user doesn't care how you made the software, but simply how well it works. If my program becomes unusable due to say, lack of memory, that's one disappointed user. Are they happy that you've sacrificed resources to make your life easier? Well, I'd like to think that such cases are extreme and that actually users will be happier that one uses Java, because I can produce better software with it. I suppose that if I knew in advance that the target machine specification was one where CPU and memory resources were at a premium, then I expect I would consider strongly the alternative technologies. But, much can be done to make your Java code more CPU and memory efficient, but you have to program specifically for that.

Summary

My experience with Java Swing (as a user and a developer) over the past year has been very positive. There was a lot of mud slung at Java in its early days and I reckon that much has stuck. This is in spite of Swing - and Java itself - being faster than ever. There's no reason that Java applications should be poor performers nowadays... unless you're low of memory, that is. Memory consumption is still a make-or-break issue, I think. The "memory is cheap" come-back is not very useful in this situation either, and I think Sun knows this and are hoping to continually improve on this issue. Yet, don't be fooled into thinking that it's only Java that can suffer from memory issues.

Despite all that's been discussed, I know that this will not help to change many peoples' minds. As Lewis and Neumann say "...in web flame wars, people are happy to discuss their speed impressions for many pages without ever referring to actual data." I'd like to think that those Java critics reading would re-examine the current state of Java, especially with the many enhancements coming in the next release. Joshua Marinacci recently blogged: "When I see an ugly webpage I don't blame my browser, I blame the site designer." This can now be applied to Java performance issues, insofar as poorly performing Java programs are due to poorly programmed Java code, and not because it's a Java program.

Probably the only real way of proving how far Java has come is by demonstation, yet Jasper pointed out:

"Java lacks the great applications that show what is possible; some are getting there like Netbeans or IntelliJ but nothing mass market. Limewire is ok, but you can't say wow! about it."

Perhaps this is why the perception of poor performance still exists: think of all the typical everyday apps one uses, such as email client, browser, IM client, media player, etc. There aren't many Java examples within those categories. I bet within the enterprise, there are lots of bespoke solutions that already show off Swing's potential - yet we'll never see them. Many Java developers are aware of Java's capabilities because many of the best examples are tools for Java developers! I've found apps like Intellij - a massive and complex Java IDE - to be blisteringly fast. Java is already good enough for the desktop, but I really believe that Mustang will be a watershed release and we'll be seeing quick growth of (well written and good performing) Java desktop apps in the next couple of years.

Thursday, December 07, 2006

Cube Platform: La Grid en Java

La plataforma Cube es un middleware que permite distribuir tareas entre los integrantes de una red Cube. De esta forma si una aplicación necesita una gran necesidad de cómputo puede obtenerlo de otras máquinas. Una tarea no es más que una clase Java. El usuario la escribe, la compila y la envia a Cube. Se encuentra en la primera beta y es totalmente funcional. La documentación aun es escasa. La licencia es GPL.

Saturday, December 02, 2006

Cursos online sobre Java (www.javapassion.com)


JAXP (all about JAXP)

The Java API for XML Processing (JAXP) lets you validate, parse, and transform XML using several different APIs. JAXP provides both ease of use and vendor neutrality. This article, the first of a two-part series introducing JAXP, shows you how to take advantage of the API's parsing and validation features. Part 2 will cover XSL transformations using JAXP.




Java technology and XML are arguably the most important programming developments of the last five years. As a result, APIs for working with XML in the Java language have proliferated. The two most popular -- the Document Object Model (DOM) and the Simple API for XML (SAX) -- have generated a tremendous amount of interest, and JDOM and data-binding APIs have followed (see Resources). Understanding even one or two of these APIs thoroughly is quite a task; using all of them correctly makes you a guru. However, more and more Java developers are finding that they no longer need extensive knowledge of SAX and DOM -- thanks largely to Sun Microsystems' JAXP toolkit. The Java API for XML Processing (JAXP) makes XML manageable for even beginning Java programmers while still providing plenty of heft for advanced developers. That said, even advanced developers who use JAXP often have misconceptions about the very API they depend on.

This article assumes that you have some basic knowledge of SAX and DOM. If you're new to XML parsing, you might want to read up on SAX and DOM first through online sources or skim through my book (see Resources). You don't need to be fluent in callbacks or DOM Nodes, but you should at least understand that SAX and DOM are parsing APIs. It would also help to have a basic understanding of their differences. This article will make a lot more sense once you've picked up these basics.


JAXP: API or abstraction?


Strictly speaking, JAXP is an API, but it is more accurately called an abstraction layer. It doesn't provide a new means of parsing XML, nor does it add to SAX or DOM, or give new functionality to Java and XML handling. (If you're in disbelief at this point, you're reading the right article.) Instead, JAXP makes it easier to use DOM and SAX to deal with some difficult tasks. It also makes it possible to handle some vendor-specific tasks that you might encounter when using the DOM and SAX APIs, in a vendor-neutral way.















Going bigtime

In earlier versions of the Java platform, JAXP was a separate download from the core platform. With Java 5.0, JAXP has become a staple of the Java language. If you've got the latest version of the JDK (see Resources), then you've already got JAXP.


Without SAX, DOM, or another XML parsing API, you cannot parse XML. I have seen many requests for a comparison of SAX, DOM, JDOM, and dom4j to JAXP, but making such comparisons is impossible because the first four APIs serve a completely different purpose from JAXP. SAX, DOM, JDOM, and dom4j all parse XML. JAXP provides a means of getting to these parsers and the data that they expose, but doesn't offer a new way to parse an XML document. Understanding this distinction is critical if you're going to use JAXP correctly. It will also most likely put you miles ahead of many of your fellow XML developers.


If you're still dubious, make sure you have the JAXP distribution (see Going bigtime). Fire up a Web browser and load the JAXP API docs. Navigate to the parsing portion of the API, located in the javax.xml.parsers package. Surprisingly, you'll find only six classes. How hard can this API be? All of these classes sit on top of an existing parser. And two of them are just for error handling. JAXP is a lot simpler than people think. So why all the confusion?















Sitting on top of the world

Even JDOM and dom4j (see Resources), like JAXP, sit on top of other parsing APIs. Although both APIs provide a different model for accessing data from SAX or DOM, they use SAX internally (with some tricks and modifications) to get at the data they present to the user.


Sun's JAXP and Sun's parser


A lot of the parser/API confusion results from how Sun packages JAXP and the parser that JAXP uses by default. In earlier versions of JAXP, Sun included the JAXP API (with those six classes I just mentioned and a few more used for transformations) and a parser, called Crimson. Crimson was part of the com.sun.xml package. In newer versions of JAXP -- included in the JDK -- Sun has repackaged the Apache Xerces parser (see Resources). In both cases, though, the parser is part of the JAXP distribution, but not part of the JAXP API.


Think about it this way: JDOM ships with the Apache Xerces parser. That parser isn't part of JDOM, but is used by JDOM, so it's included to ensure that JDOM is usable out of the box. The same principle applies for JAXP, but it isn't as clearly publicized: JAXP comes with a parser so it can be used immediately. However, many people refer to the classes included in Sun's parser as part of the JAXP API itself. For example, a common question on newsgroups used to be, "How can I use the XMLDocument class that comes with JAXP? What is its purpose?" The answer is somewhat complicated.















What's in a (package) name?

When I first cracked open the source code to Java 1.5, I was surprised at what I saw -- or rather, at what I did not see. Instead of finding Xerces in it's normal package, org.apache.xerces, Sun relocated the Xerces classes to com.sun.org.apache.xerces.internal. (I find this a little disrespectful, but nobody asked me.) In any case, if you're looking for Xerces in the JDK, that's where it is.


First, the com.sun.xml.tree.XMLDocument class is not part of JAXP. It is part of Sun's Crimson parser, packaged in earlier versions of JAXP. So the question is misleading from the start. Second, a major purpose of JAXP is to provide vendor independence when dealing with parsers. With JAXP, you can use the same code with Sun's XML parser, Apache's Xerces XML parser, and Oracle's XML parser. Using a Sun-specific class, then, violates the point of using JAXP. Are you starting to see how this subject has gotten muddied? The parser and the API in the JAXP distribution have been lumped together, and some developers mistake classes and features from one as part of the other, and vice versa.


Now that you can see beyond all the confusion, you're ready to move on to some code and concepts.

























Back to top





Starting with SAX


SAX is an event-driven methodology for processing XML. It consists of many callbacks. For example, the startElement() callback is invoked every time a SAX parser comes across an element's opening tag. The characters() callback is called for character data, and then endElement() is called for the element's end tag. Many more callbacks are present for document processing, errors, and other lexical structures. You get the idea. The SAX programmer implements one of the SAX interfaces that defines these callbacks. SAX also provides a class called DefaultHandler (in the org.xml.sax.helpers package) that implements all of these callbacks and provides default, empty implementations of all the callback methods. (You'll see that this is important in my discussion of DOM in the next section, Dealing with DOM.) The SAX developer needs only extend this class, then implement methods that require insertion of specific logic. So the key in SAX is to provide code for these various callbacks, then let a parser trigger each of them when appropriate. Here's the typical SAX routine:



  1. Create a SAXParser instance using a specific vendor's parser implementation.

  2. Register callback implementations (by using a class that extends DefaultHandler, for example).

  3. Start parsing and sit back as your callback implementations are fired off.


JAXP's SAX component provides a simple means for doing all of this. Without JAXP, a SAX parser instance either must be instantiated directly from a vendor class (such as org.apache.xerces.parsers.SAXParser), or it must use a SAX helper class called XMLReaderFactory (also in the org.xml.sax.helpers package). The problem with the first methodology is obvious: It isn't vendor neutral. The problem with the second is that the factory requires, as an argument, the String name of the parser class to use (that Apache class, org.apache.xerces.parsers.SAXParser, again). You can change the parser by passing in a different parser class as a String. With this approach, if you change the parser name, you won't need to change any import statements, but you will still need to recompile the class. This is obviously not a best-case solution. It would be much easier to be able to change parsers without recompiling the class.


JAXP offers that better alternative: It lets you provide a parser as a Java system property. Of course, when you download a distribution from Sun, you get a JAXP implementation that uses Sun's version of Xerces. Changing the parser -- say, to Oracle's parser -- requires that you change a classpath setting, moving from one parser implementation to another, but it does not require code recompilation. And this is the magic -- the abstraction -- that JAXP is all about.















Sneaky SAX developers

I'm hedging a bit. With a little clever coding, you can make a SAX application pick up the parser class to use from a system property or a properties file. However, JAXP gives you this same behavior without any work at all, so many of you are better off going the JAXP route.


A look at the SAX parser factory


The JAXP SAXParserFactory class is the key to being able to change parser implementations easily. You must create a new instance of this class (which I'll look at in a moment). After the new instance is created, the factory provides a method for obtaining a SAX-capable parser. Behind the scenes, the JAXP implementation takes care of the vendor-dependent code, keeping your code happily unpolluted. This factory has some other nice features, as well.


In addition to the basic job of creating instances of SAX parsers, the factory lets you set configuration options. These options affect all parser instances obtained through the factory. The two most commonly used options available in JAXP 1.3 are to set namespace awareness with setNamespaceAware(boolean awareness), and to turn on DTD validation with setValidating(boolean validating). Remember that once these options are set, they affect all instances obtained from the factory after the method invocation.


Once you have set up the factory, invoking newSAXParser() returns a ready-to-use instance of the JAXP SAXParser class. This class wraps an underlying SAX parser (an instance of the SAX class org.xml.sax.XMLReader). It also protects you from using any vendor-specific additions to the parser class. (Remember the discussion about the XmlDocument class earlier in this article?) This class allows actual parsing behavior to be kicked off. Listing 1 shows how you can create, configure, and use a SAX factory:




Listing 1. Using the SAXParserFactory







  import java.io.OutputStreamWriter;
import java.io.Writer;
// JAXP
import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.parsers.SAXParserFactory;
import javax.xml.parsers.SAXParser;
// SAX
import org.xml.sax.Attributes;
import org.xml.sax.SAXException;
import org.xml.sax.helpers.DefaultHandler;
public class TestSAXParsing {
public static void main(String[] args) {
try {
if (args.length != 1) {
System.err.println ("Usage: java TestSAXParsing [filename]");
System.exit (1);
}
// Get SAX Parser Factory
SAXParserFactory factory = SAXParserFactory.newInstance();
// Turn on validation, and turn off namespaces
factory.setValidating(true);
factory.setNamespaceAware(false);
SAXParser parser = factory.newSAXParser();
parser.parse(new File(args[0]), new MyHandler());
} catch (ParserConfigurationException e) {
System.out.println("The underlying parser does not support " +
" the requested features.");
} catch (FactoryConfigurationError e) {
System.out.println("Error occurred obtaining SAX Parser Factory.");
} catch (Exception e) {
e.printStackTrace();
}
}
}
class MyHandler extends DefaultHandler {
// SAX callback implementations from ContentHandler, ErrorHandler, etc.
}



In Listing 1, you can see that two JAXP-specific problems can occur in using the factory: the inability to obtain or configure a SAX factory, and the inability to configure a SAX parser. The first of these problems, represented by a FactoryConfigurationError, usually occurs when the parser specified in a JAXP implementation or system property cannot be obtained. The second problem, represented by a ParserConfigurationException, occurs when a requested feature is not available in the parser being used. Both are easy to deal with and shouldn't pose any difficulty when using JAXP. In fact, you might want to write code that attempts to set several features and gracefully handles situations where a certain feature isn't available.


A SAXParser instance is obtained once you get the factory, turn off namespace support, and turn on validation; then parsing begins. The SAX parser's parse() method takes an instance of the SAX HandlerBase helper class that I mentioned earlier, which your custom handler class extends. See the code distribution to view the implementation of this class with the complete Java listing (see Download). You also pass in the File to parse. However, the SAXParser class contains much more than this single method.


Working with the SAX parser


Once you have an instance of the SAXParser class, you can do a lot more than just pass it a File to parse. Because of the way components in large applications communicate, it's not always safe to assume that the creator of an object instance is its user. One component might create the SAXParser instance, while another component (perhaps coded by another developer) might need to use that same instance. For this reason, JAXP provides methods to determine the parser's settings. For example, you can use isValidating() to determine if the parser will -- or will not -- perform validation, and isNamespaceAware() to see if the parser can process namespaces in an XML document. These methods can give you information about what the parser can do, but users with just a SAXParser instance -- and not the SAXParserFactory itself -- do not have the means to change these features. You must do this at the parser factory level.


You also have a variety of ways to request parsing of a document. Instead of just accepting a File and a SAX DefaultHandler instance, the SAXParser's parse() method can also accept a SAX InputSource, a Java InputStream, or a URL in String form, all with a DefaultHandler instance. So you can still parse documents wrapped in various forms.


Finally, you can obtain the underlying SAX parser (an instance of org.xml.sax.XMLReader) and use it directly through the SAXParser's getXMLReader() method. Once you get this underlying instance, the usual SAX methods are available. Listing 2 shows examples of the various uses of the SAXParser class, the core class in JAXP for SAX parsing:




Listing 2. Using the JAXP SAXParser class







    // Get a SAX Parser instance
SAXParser saxParser = saxFactory.newSAXParser();
// Find out if validation is supported
boolean isValidating = saxParser.isValidating();
// Find out if namespaces are supported
boolean isNamespaceAware = saxParser.isNamespaceAware();
// Parse, in a variety of ways
// Use a file and a SAX DefaultHandler instance
saxParser.parse(new File(args[0]), myDefaultHandlerInstance);
// Use a SAX InputSource and a SAX DefaultHandler instance
saxParser.parse(mySaxInputSource, myDefaultHandlerInstance);
// Use an InputStream and a SAX DefaultHandler instance
saxParser.parse(myInputStream, myDefaultHandlerInstance);
// Use a URI and a SAX DefaultHandler instance
saxParser.parse("http://www.newInstance.com/xml/doc.xml",
myDefaultHandlerInstance);
// Get the underlying (wrapped) SAX parser
org.xml.sax.XMLReader parser = saxParser.getXMLReader();
// Use the underlying parser
parser.setContentHandler(myContentHandlerInstance);
parser.setErrorHandler(myErrorHandlerInstance);
parser.parse(new org.xml.sax.InputSource(args[0]));



Up to this point, I've talked a lot about SAX, but I haven't unveiled anything remarkable or surprising. JAXP's added functionality is fairly minor, especially where SAX is involved. This minimal functionality makes your code more portable and lets other developers use it, either freely or commercially, with any SAX-compliant XML parser. That's it. There's nothing more to using SAX with JAXP. If you already know SAX, you're about 98 percent of the way there. You just need to learn two new classes and a couple of Java exceptions, and you're ready to roll. If you've never used SAX, it's easy enough to start now.

























Back to top





Dealing with DOM


If you think you need to take a break to gear up for the challenge of DOM, you can save yourself some rest. Using DOM with JAXP is nearly identical to using it with SAX; all you do is change two class names and a return type, and you are pretty much there. If you understand how SAX works and what DOM is, you won't have any problem.


The primary difference between DOM and SAX is the structures of the APIs themselves. SAX consists of an event-based set of callbacks, while DOM has an in-memory tree structure. With SAX, there's never a data structure to work on (unless the developer creates one manually). SAX, therefore, doesn't give you the ability to modify an XML document. DOM does provide this functionality. The org.w3c.dom.Document class represents an XML document and is made up of DOM nodes that represent the elements, attributes, and other XML constructs. So JAXP doesn't need to fire SAX callbacks; it's responsible only for returning a DOM Document object from parsing.


A look at the DOM parser factory


With this basic understanding of DOM and the differences between DOM and SAX, you don't need to know much more. The code in Listing 3 looks remarkably similar to the SAX code in Listing 1. First, a DocumentBuilderFactory is obtained (in the same way that SAXParserFactory was in Listing 1). Then the factory is configured to handle validation and namespaces (in the same way that it was in SAX). Next, a DocumentBuilder instance, the analog to SAXParser, is retrieved from the factory (in the same way . . . you get the idea). Parsing can then occur, and the resultant DOM Document object is handed off to a method that prints the DOM tree:




Listing 3. Using the DocumentBuilderFactory







  import java.io.File;
import java.io.IOException;
import java.io.OutputStreamWriter;
import java.io.Writer;
// JAXP
import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.DocumentBuilder;
// DOM
import org.w3c.dom.Document;
import org.w3c.dom.DocumentType;
import org.w3c.dom.NamedNodeMap;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;
public class TestDOMParsing {
public static void main(String[] args) {
try {
if (args.length != 1) {
System.err.println ("Usage: java TestDOMParsing " +
"[filename]");
System.exit (1);
}
// Get Document Builder Factory
DocumentBuilderFactory factory =
DocumentBuilderFactory.newInstance();
// Turn on validation, and turn off namespaces
factory.setValidating(true);
factory.setNamespaceAware(false);
DocumentBuilder builder = factory.newDocumentBuilder();
Document doc = builder.parse(new File(args[0]));
// Print the document from the DOM tree and
// feed it an initial indentation of nothing
printNode(doc, "");
} catch (ParserConfigurationException e) {
System.out.println("The underlying parser does not " +
"support the requested features.");
} catch (FactoryConfigurationError e) {
System.out.println("Error occurred obtaining Document " +
"Builder Factory.");
} catch (Exception e) {
e.printStackTrace();
}
}
private static void printNode(Node node, String indent) {
// print the DOM tree
}
}



Two problems can arise with this code (as with SAX in JAXP): a FactoryConfigurationError and a ParserConfigurationException. The cause of each is the same as it is with SAX. Either a problem is present in the implementation classes (resulting in a FactoryConfigurationError), or the parser provided doesn't support the requested features (resulting in a ParserConfigurationException). The only difference between DOM and SAX in this respect is that with DOM you substitute DocumentBuilderFactory for SAXParserFactory, and DocumentBuilder for SAXParser. It's that simple. (You can view the complete code listing, which includes the method used to print out the DOM tree; see Download.)


Working with the DOM parser


Once you have a DOM factory, you can obtain a DocumentBuilder instance. The methods available to a DocumentBuilder instance are very similar to those available to its SAX counterpart. The major difference is that variations of the parse() method do not take an instance of the SAX DefaultHandler class. Instead they return a DOM Document instance representing the XML document that was parsed. The only other difference is that two methods are provided for SAX-like functionality:



  • setErrorHandler(), which takes a SAX ErrorHandler implementation to handle problems that might arise in parsing

  • setEntityResolver(), which takes a SAX EntityResolver implementation to handle entity resolution


Listing 4 shows examples of these methods in action:




Listing 4. Using the JAXP DocumentBuilder class







    // Get a DocumentBuilder instance
DocumentBuilder builder = builderFactory.newDocumentBuilder();
// Find out if validation is supported
boolean isValidating = builder.isValidating();
// Find out if namespaces are supported
boolean isNamespaceAware = builder.isNamespaceAware();
// Set a SAX ErrorHandler
builder.setErrorHandler(myErrorHandlerImpl);
// Set a SAX EntityResolver
builder.setEntityResolver(myEntityResolverImpl);
// Parse, in a variety of ways
// Use a file
Document doc = builder.parse(new File(args[0]));
// Use a SAX InputSource
Document doc = builder.parse(mySaxInputSource);
// Use an InputStream
Document doc = builder.parse(myInputStream, myDefaultHandlerInstance);
// Use a URI
Document doc = builder.parse("http://www.newInstance.com/xml/doc.xml");



If you're a little bored reading this section on DOM, you're not alone; I found it a little boring to write because applying what you've learned about SAX to DOM is so straightforward.

























Back to top





Performing validation


In Java 5.0 (and JAXP 1.3), JAXP introduces a new way to validate documents. Instead of simply using the setValidating() method on a SAX or DOM factory, validation is broken out into several classes within the new javax.xml.validation package. I would need more space than I have in this article to detail all the nuances of validation -- including W3C XML Schema, DTDs, RELAX NG schemas, and other constraint models -- but if you already have some constraints, it's pretty easy to use the new validation model and ensure that your document matches up with them.















Redundancy isn't always good

One thing you should not do is use setValidating(true) and the javax.xml.validation package. You'll get some nasty errors, and most of them are hard to track down. It's best to make a habit of never calling setValidating() -- which defaults to false -- and to use the new JAXP validation framework instead.


First, convert your constraint model -- presumably a file on disk somewhere -- into a format that JAXP can use. Load the file into a Source instance. (I'll cover Source in more detail in Part 2; for now, just know that it represents a document somewhere, on disk, as a DOM Document or just about anything else.) Then, create a SchemaFactory and load the schema using SchemaFactory.newSchema(Source), which returns a new Schema object. Finally, with this Schema object, create a new Validator object with Schema.newValidator(). Listing 5 should make everything I've just said much clearer:




Listing 5. Using the JAXP validation framework







    DocumentBuilder builder = factory.newDocumentBuilder();
Document doc = builder.parse(new File(args[0]));
// Handle validation SchemaFactory constraintFactory =
SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
Source constraints = new StreamSource(new File(args[1]));
Schema schema = constraintFactory.newSchema(constraints);
Validator validator = schema.newValidator();
// Validate the DOM tree
try {
validator.validate(new DOMSource(doc));
System.out.println("Document validates fine.");
} catch (org.xml.sax.SAXException e) {
System.out.println("Validation error: " + e.getMessage());
}



This is pretty straightforward once you get the hang of it. Type this code in yourself, or check out the full listing (see Download).

























Back to top





Changing the parser


It's easy to change out the parser that the JAXP factory classes use. Changing the parser actually means changing the parser factory, because all SAXParser and DocumentBuilder instances come from these factories. The factories determine which parser is loaded, so it's the factories that you must change. To change the implementation of the SAXParserFactory interface, set the Java system property javax.xml.parsers.SAXParserFactory. If this property isn't defined, then the default implementation (whatever parser your vendor specified) is returned. The same principle applies for the DocumentBuilderFactory implementation you use. In this case, the javax.xml.parsers.DocumentBuilderFactory system property is queried.

























Back to top





Summary


Having read this article, you've seen almost the entire scope of JAXP:



  • Provide hooks into SAX

  • Provide hooks into DOM

  • Allow the parser to easily be changed out


To understand JAXP's parsing and validation features, you'll wade through very little tricky material. The most difficult parts of putting JAXP to work are changing a system property, setting validation through a factory instead of a parser or builder, and getting clear on what JAXP isn't. JAXP provides a helpful pluggability layer over two popular Java and XML APIs. It makes your code vendor neutral and lets you to change from parser to parser without ever recompiling your parsing code. So download JAXP and go to it! Part 2 will show you how JAXP can help you transform XML documents.
























Back to top





Download

















Description Name Size Download method
Sample code for All about JAXP x-jaxp-all-about.zip 5 KB FTP

JAXP (Java XML)

Introduction


After the first release of the W3C XML 1.0 recommendation in early 1998, XML started gaining huge popularity. Sun Microsystems Inc., at that time had just formalized the Java Community Process (JCP), and the first version of JAXP (JSR-05) was made public in early 2000, supported by industry majors like (in chronological order) BEA Systems, Fujitsu Limited, Hewlett-Packard, IBM, Netscape Communications, Oracle, and Sun Microsystems, Inc.

JAXP 1.0, then called Java API for XML Parsing, was a box office hit in the developer community, because of the pluggability layer provided by JAXP; that's what the essence of JAXP is. Developers can write program independent of the underlying XML processor by using the JAXP APIs, and can replace the underlying XML processor by choice without even changing a single line of application code.


So what exactly is JAXP? First of all, there has been some confusion in the past about the P in JAXP: Parsing or Processing? Because JAXP 1.0 supported only parsing, therefore, it was called Java API for XML Parsing. But in JAXP 1.1 (JSR-63), XML transformation was introduced using XSL-T. Unfortunately, the W3C XSL-T specification does not provide any APIs for transformation. Therefore, the JAXP 1.1 Expert Group (EG) introduced a set of APIs called Transformation API for XML (TrAX) in JAXP 1.1, and since then, JAXP is called Java API for XML Processing. Thereafter, JAXP has evolved to an extent, where now it supports a lot more things (like validation against schema while parsing, validation against preparsed schema, evaluating XPath expressions, etc.,) than only parsing an XML document.





So, JAXP is a lightweight API to process XML documents by being agnostic of the underlying XML processor, which are pluggable.


XML Parsing Using JAXP


JAXP supports Object-based and Event-based parsing. In Object-based, only W3C DOM parsing is supported so far. Maybe in future versions of JAXP, the EG might decide to support J-DOM as well. In Event-based, only SAX parsing is supported. Another Event-based parsing called Pull Parsing, should have been made part of JAXP. But, there is a different JSR (#173) filed for pull parsing, also known as Streaming API for XML (StAX) parsing, and nothing much can be done about that now.


Figure 1

Figure 1: Various mechanism of parsing XML.


Simple API for XML (SAX) Parsing

SAX APIs were proposed by David Megginson (in early 1998) as an effort towards a standard API for event-based parsing of XML (read the genesis of SAX here). Even though SAX is not a W3C REC, it is surely the de facto industry standard for parsing XML documents.


SAX parsing is an event-based, push-parsing mechanism, which generates events for the <opening> tags, </closing> tags, the character data, and so on. A SAX parser parses an XML document in a streaming fashion (forward only) and reports the events, in the sequence encountered, to the registered content handler, org.xml.sax.ContentHandler, (Don't get confused with the java.net.ContentHandler.) and errors (if any) to the registered error handler, org.xml.sax.ErrorHandler.


If you don't register an error handler, you will never know if there was any error while parsing the XML, and what it was. Therefore, it becomes extremely important to always register a meaningful error handler while SAX parsing an XML document.


If the application needs to be informed of the parsing events (and process it), it must implement the org.xml.sax.ContentHandler interface and register it with the SAX parser. A typical sequence of events reported through the callbacks could be startDocument, startElement, characters, endElement, endDocument, in that order. startDocument is called only once before reporting any other event. Similarly, endDocument is called only once after the entire XML is parsed successfully. See the javadocs for more details.


Figure 2

Figure 2: SAX Parsing XML


Snippet to SAX parse an XML document using JAXP:


        SAXParserFactory spfactory = SAXParserFactory.newInstance();
spfactory.setNamespaceAware(true);
SAXParser saxparser = spfactory.newSAXParser();
//write your handler for processing events and handling error
DefaultHandler handler = new MyHandler();
//parse the XML and report events and errors (if any) to the handler
saxparser.parse(new File("data.xml"), handler);

Document Object Model (DOM) Parsing

DOM parsing is an object-based parsing mechanism, which generates an XML object model: an inverted tree-like data structure, which represents the XML document. Every element node in the object model represents a pair of <opening> and </closing> tags in the XML. A DOM parser reads the entire XML file and creates an in-memory data structure called DOM. If the DOM parser is W3C compliant, then, the DOM created is a W3C DOM, which can be traversed or modified using the org.w3c.dom APIs.


Most of the DOM parsers also allow you to create an in-memory DOM structure from scratch, rather than just parsing an XML to a DOM.


Figure 3

Figure 3: DOM Parsing XML


Snippet to DOM parse an XML document using JAXP:


          DocumentBuilderFactory dbfactory = DocumentBuilderFactory.newInstance();
dbfactory.setNamespaceAware(true);
DocumentBuilder domparser = dbfactory.newDocumentBuilder();
//parse the XML and create the DOM
Document doc = domparser.parse(new File("data.xml"));
//to create a new DOM from scratch -
//Document doc = domparser.newDocument();
//once you have the Document handle, then you can use
//the org.w3c.dom.* APIs to traverse or modify the DOM...

Parsing in Validating Mode


Validation Against DTD

DTD is a grammar for XML documents. Often people think that DTD is something alien because it has a different syntax than XML, but DTD is an integral part of W3C XML 1.0. If an XML instance document has a DOCTYPE declaration, then to turn on validation against DTD, while parsing XML, you need to set the validating feature to true using the setValidating method on the appropriate factory. For example:


        DocumentBuilderFactory dbfactory = DocumentBuilderFactory.newInstance();
dbfactory.setValidating(true);
OR
SAXParserFactory spfactory = SAXParserFactory.newInstance();
spfactory.setValidating(true);

Note that, even if the validation is turned off, and if the XML instance has a DOCTYPE declaration to an external DTD, the parser always tries to load that DTD. This is done to ensure that any entity references in the XML instance (entity declarations being in the DTD) are expanded properly, which otherwise might lead to a malformed XML document, until and unless the standalone attribute on the XML declaration prolog is set to true, in which case the external DTD is ignored completely. For example:


        <?xml version="1.1" encoding="UTF-8" standalone="yes"?>          

Validation Against W3C XMLSchema (WXS)

XMLSchema is yet another grammar for XML documents, and has gained huge popularity because of the XML syntax it uses, and the richness it provides to define fine grained validation constraints. If an XML instance document points to XMLSchema using the "schemaLocation" and "noNamespaceSchemaLocation" hints, then to turn on validation against XMLSchema, you need to do the following things:



  1. Set the validating feature to true using the setValidating method on SAXParserFactory or DocumentBuilderFactory, as mentioned above.

  2. Set the property "http://java.sun.com/xml/jaxp/properties/schemaLanguage" with the corresponding value as "http://www.w3.org/2001/XMLSchema"


Note that, in this case, even if a DOCTYPE exists in the XML instance, the instance won't be validated against DTD. But as mentioned earlier, surely it would be loaded so that any entity references can be expanded properly.


Since "schemaLocation" and "noNamespaceSchemaLocation" are just hints, the schemas can also be provided externally to override these hints, using the property "http://java.sun.com/xml/jaxp/properties/schemaSource". The acceptable value for this property must be one of the following:



  • java.lang.String that points to the URI of the schema

  • java.io.InputStream with the contents of the schema

  • org.xml.sax.InputSource

  • java.io.File

  • an array of java.lang.Object with the contents being one of the types defined above.


For example:


        SAXParserFactory spfactory = SAXParserFactory.newInstance();
spfactory.setNamespaceAware(true);
//turn the validation on
spfactory.setValidating(true);
//set the validation to be against WXS
saxparser.setProperty("http://java.sun.com/xml/jaxp/properties/
schemaLanguage", "http://www.w3.org/2001/XMLSchema");
//set the schema against which the validation is to be done
saxparser.setProperty("http://java.sun.com/xml/jaxp/properties/
schemaSource", new File("myschema.xsd"));

XML Transformation Using the TrAX APIs in JAXP


W3C XSL-T defines transformation rules to transform a source tree into a result tree. A transformation expressed in XSL-T is called a stylesheet. To transform an XML document using JAXP, you need to create a Transformer using the stylesheet. Once a Transformer is created, it takes the XML input to be transformed as a JAXP Source, and returns the transformed result as a JAXP Result. There are three types of sources and results that JAXP provides: StreamSource, SAXSource, DOMSource and StreamResult, SAXResult, DOMResult, which can be used in any combination for transformation.


Figure 4

Figure: XML Transformation


For example, to generate SAX events from DOM:


        //parse the XML file to a W3C DOM
DocumentBuilderFactory dbfactory = DocumentBuilderFactory.newInstance();
dbfactory.setNamespaceAware(true);
DocumentBuilder domparser = dbfactory.newDocumentBuilder();
Document doc = domparser.parse(new File("data.xml"));
//prepare the DOM source
Source xmlsource = new DOMSource(doc);
//create a content handler to handle the SAX events
ContentHandler handler = new MyHandler();
//prepare a SAX result using the content handler
Result result = new SAXResult(handler);
//create a transformer factory
TransformerFactory xfactory = TransformerFactory.newInstance();
//create a transformer
Transformer xformer = xfactory.newTransformer();
//transform to raise the SAX events from DOM
xformer.transform(xmlsource, result);

In the above example, we haven't used any XSL while creating the Transformer. This means the Transformer would merely pour the XML from the Source to the Result without any transformation. When you want to actually transform using a XSL, then you should create the Transformer using the XSL source as follows:


        //create the xsl source
Source xslsource = new StreamSource(new File("mystyle.xsl"));
//create the transformer using the xsl source
Transformer xformer = xfactory.newTransformer(xslsource);

What's New in JAXP 1.3


Apart from supporting SAX parsing, DOM parsing, validation against DTD/XMLSchema while parsing, transformation using XSL-T, from the previous versions, JAXP 1.3 additionally supports:



  1. XML 1.1 and Namespaces in XML 1.1

  2. XML Inclusions - XInclude 1.0

  3. Validation of instance against preparsed schema (XMLSchema and RELAX-NG).

  4. Evaluating XPath expressions.

  5. XML/Java type mappings for those datatypes in XMLSchema 1.0, XPath 2.0 and XQuery 1.0 for which there wasn't any XML/Java mappings earlier.


Using JAXP 1.3


XML 1.1 and XInclude 1.0


Major things supported in XML 1.1 are:



  1. forward compatibility for the ever-growing Unicode character set.

  2. addition of NEL (#x85) and the Unicode line separator character (#x2028) to the list of line-end characters.


Changes in XML 1.1 are not fully backward compatible with XML 1.0 and also break the well-formedness rules defined in XML 1.0. Therefore, a new specification, XML 1.1, was proposed rather than simply updating the existing XML 1.0 specification.


To use XML 1.1 and the Namespaces in XML 1.1 feature, you must set the value of the version attribute, in the XML declaration prolog, of your XML document, to "1.1." For example:


        <?xml version="1.1" encoding="UTF-8" standalone="yes"?>          

XInclude allows an XML document to include other XML documents. For example:


        <myMainXMLDoc xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="fragment.xml"/>
  ...
</myMainXMLDoc>

To allow XML inclusions, you must set the XInclude feature on the appropriate factory as follows:


        DocumentBuilderFactory dbfactory = DocumentBuilderFactory.newInstance();
dbfactory.setXIncludeAware(true);

Validating a JAXP Source Against a Preparsed Schema


javax.xml.validation package provides support for parsing a schema, and validating XML instance documents against those preparsed schemas. A JAXP DOMSource or a SAXSource can be validated against a preparsed schema. The preparsed schema can be cached for optimization, if required. Note that the JAXP StreamSource is not supported and that the schema can be either a W3C XML Schema or an OASIS RELAX-NG. For example:


          //parse an XML in non-validating mode and create a DOMSource
DocumentBuilderFactory dbfactory = DocumentBuilderFactory.newInstance();
dbfactory.setNamespaceAware(true);
dbfactory.setXIncludeAware(true);
DocumentBuilder parser = dbfactory.newDocumentBuilder();
Document doc = parser.parse(new File("data.xml"));
DOMSource xmlsource = new DOMSource(doc);
//create a SchemaFactory for loading W3C XML Schemas
SchemaFactory wxsfactory =
SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
//set the errorhandler for handling errors in schema itself
wxsfactory.setErrorHandler(schemaErrorHandler);
//load a W3C XML Schema
Schema schema = wxsfactory.newSchema(new File("myschema.xsd"));
// create a validator from the loaded schema
Validator validator = schema.newValidator();
//set the errorhandler for handling validation errors
validator.setErrorHandler(validationErrorHandler);
//validate the XML instance
validator.validate(xmlsource);

Evaluating XPath Expressions


javax.xml.xpath package provides support for executing XPath expressions against a given XML document. The XPath expressions can be compiled for performance reasons, if it is to be reused.


By the way, the XPath APIs in JAXP are designed to be stateless, which means every time you  want to evaluate an XPath expression, you also need to pass in the XML document. Often, many XPath expressions are evaluated against a single XML document. In such a case, it would have been better if the XPath APIs in JAXP were made stateful by passing the XML document once. The underlying implementation would then have had a choice of storing the XML source in an optimized fashion (say, a DTM) for faster evaluation of XPath expressions.


An example to evaluate the XPath expressions against the following XML document:


        <?xml version="1.0"?>
<employees>
<employee>
<name>e1</name>
</employee>
<employee>
<name>e2</name>
</employee>
</employees>

          //parse an XML to get a DOM to query
DocumentBuilderFactory dbfactory = DocumentBuilderFactory.newInstance();
dbfactory.setNamespaceAware(true);
dbfactory.setXIncludeAware(true);
DocumentBuilder parser = dbfactory.newDocumentBuilder();
Document doc = parser.parse(new File("data.xml"));
//get an XPath processor
XPathFactory xpfactory = XPathFactory.newInstance();
XPath xpathprocessor = xpfactory.newXPath();
//set the namespace context for resolving prefixes of the Qnames
//to NS URI, if the xpath expresion uses Qnames. XPath expression
//would use Qnames if the XML document uses namespaces.
//xpathprocessor.setNamespaceContext(NamespaceContext nsContext);
//create XPath expressions
String xpath1 = "/employees/employee";
XPathExpression employeesXPath = xpathprocessor.compile(xpath1);
String xpath2 = "/employees/employee[1]";
XPathExpression employeeXPath  = xpathprocessor.compile(xpath2);
String xpath3 = "/employees/employee[1]/name";
XPathExpression empnameXPath  = xpathprocessor.compile(xpath3);
//execute the XPath expressions
System.out.println("XPath1="+xpath1);
NodeList employees = (NodeList)employeesXPath.evaluate(doc,
XPathConstants.NODESET);
for (int i=0; i<employees.getLength(); i++) {
System.out.println(employees.item(i).getTextContent());
}
System.out.println("XPath2="+xpath2);
Node employee = (Node)employeeXPath.evaluate(doc, XPathConstants.NODE);
System.out.println(employee.getTextContent());
System.out.println("XPath3="+xpath3);
String empname = empnameXPath.evaluate(doc);
System.out.println(empname);

XML/Java-type Mappings


Datatypes in XMLSchema 1.0 are quite exhaustive and popular, and are used by many other XML specifications as well, like XPath, XQuery, WSDL, etc... Most of these datatypes naturally map to the primitive or wrapper datatypes in Java. The rest of the datatypes like dateTime, duration, etc., can be mapped to the new Java types: javax.xml.datatype.XMLGregorianCalendar, javax.xml.datatype.Duration, and javax.xml.namespace.QName. Thus, along with the new datatypes defined in javax.xml.datatype package, all the datatypes supported in XMLSchema 1.0, XPath 2.0 and XQuery 1.0 now have an equivalent datatype mapping in Java.


But, the datatype support would have been much better from a usability perspective if the DatatypeFactory had methods to get a Java object for the given WXS datatype, which has methods to constrain the datatypes using facets, and validate a value against the datatype.


An example using Oracle's XDK:


          import oracle.xml.parser.schema.*;
. . .
//create a simpleType object
XSDSimpleType st = XSDSimpleType.getPrimitiveType(XSDSimpleType.iSTRING);
//set a constraining facet on the simpleType
st.setFacet(XSDSimpleType.LENGTH, "5");
//validate value
st.validateValue("hello");

Changing the Underlying Implementation


A JAXP implementation comes with a default parser, transformer, xpath engine, and a schema validator, but, as mentioned earlier, JAXP is a pluggable API, and we can plug in any JAXP complaint processor to change the defaults. To do that we must set the appropriate javax.xml.xxx.yyyFactory property pointing to the fully qualified class name of the new yyyFactory. Then, when yyyFactory.newInstance() is invoked, JAXP uses the following ordered lookup procedure to determine the implementation class to load:



  1. Use the javax.xml.xxx.yyyFactory system property.

  2. Use the properties file "lib/jaxp.properties" in the JRE directory. The jaxp.properties file is read only once by the JAXP 1.3 implementation and its values are then cached for future use. If the file does not exist when the first attempt is made to read from it, no further attempts are made to check for its existence. It is not possible to change the value of any property in jaxp.properties after it has been read for the first time.

  3. Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for the classname in the file META-INF/services/javax.xml.xxx.yyyFactory in jars available to the runtime.

  4. Use the platform default javax.xml.xxx.yyyFactory instance


where javax.xml.xxx.yyyFactory can be one of the following:

javax.xml.parsers.SAXParserFactory

javax.xml.parsers.DocumentBuilderFactory

javax.xml.transform.TransformerFactory

javax.xml.xpath.XPathFactory

javax.xml.validation.SchemaFactory:schemaLanguage (schemaLanguage is the parameter passed to the newInstance method of SchemaFactory)


For example, to plug in a JAXP complaint SAX parser, say Apache's Xerces, you must set the property javax.xml.parsers.SAXParserFactory to org.apache.xerces.jaxp.SAXParserFactoryImpl, in any of the four ways mentioned above. One of the ways is shown below:


       java -Djavax.xml.parsers.SAXParserFactory=
org.apache.xerces.jaxp.SAXParserFactoryImpl MyApplicationProgram