The Classic "Hello World" with JColtrane
Now we are gonna make the same parsing, using the same XML document showed in last section. We will do this in steps, so you can back to it whenever you want when using JColtrane in your aplications.
Step 1 - Creating a Class
Let's create the class with some methods you want execute when parsing the XML document:
public class HelloWorld {
public void executeInStartDocument(){
System.out.println("Hello World!!!\n");
}
public void executeInEndDocument(){
System.out.println("Bye bye World!!!\n");
}
public void executeInStartElement(){
System.out.println("Executing something in start element\n");
}
public void executeInEndElement(){
System.out.println("Executing something in end element\n");
}
}
We wrote the method's names indicating when we want to execute them, just for didatic purpose. Of course, you can use whatever name you want in your own classes.
Step 2 - Defining Conditions
Now we have our class, let's tell JColtrane when to execute the methods:
public class HelloWorld {
@StartDocument
public void executeInStartDocument(){
System.out.println("Hello World!!!\n");
}
@EndDocument
public void executeInEndDocument(){
System.out.println("Bye bye World!!!\n");
}
@StartElement
public void executeInStartElement(){
System.out.println("Executing something in start element\n");
}
@EndElement
public void executeInEndElement(){
System.out.println("Executing something in end element\n");
}
}
As you can note, we just annoted the methods telling JColtrane when to execute the methods. Those 4 annotations (StartDocument, EndDocument, StartElement and EndElement) are the base conditions in JColtrane. We will soon see in details how to use them to make sophisticated conditions.
Step 3 - Passing Created Class as Parameter in JColtraneXMLHandler's Construtor
Now we have a class, which methods are annoted telling when to execute, let's deliver one instance of HellorWorld to JColtraneXMLHandler, the class that make the magic happens. We will do this on class JColtraneHandlerTest, that is similar to SAXHandlerTest viewed in last section, with just 1 modificated line of code, that is highlighted:
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
public class JColtraneHandlerTest {
public static void main(String[] args) {
SAXParser parser=null;
try {
parser= SAXParserFactory.newInstance().newSAXParser();
} catch (ParserConfigurationException e) {
e.printStackTrace();
} catch (SAXException e) {
e.printStackTrace();
}
File file=new File("examples\\example1\\Example1.xml");
if(parser!=null){
InputSource input=new InputSource(file.getAbsolutePath());
try {
parser.parse(input,new JColtraneXMLHandler(new HelloWorld()));
} catch (SAXException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
}
}
}
}
So, after defining in which conditions to execute the methods and passing HelloWorld as parameter to JColtraneXMLHandler, we use it in the same way we used SAXHandler to parse the XML document. The system reponse when running JColtraineHandlerTest was:
Hello World!!!
Executing something in start element
Executing something in start element
Executing something in start element
Executing something in end element
Executing something in end element
Executing something in end element
Bye bye World!!!
At this point, you think: "That's ok, I make JColtrane execute the methods I want in the way I want, but I remember from example presented in last section that system print the current brunch from XML document and its body. How can I acces the parameters I need?". So, to answer your good question, let's go to step 4.
Step 4 - Choosing The Exactly Parameters I Need
When using SAX you must acces some parameters which you could use to realise your parse. From the example from last section, we want to build a current brunch and a body. Let's make some changes in HelloWord's code. These changes are highlighted:
public class HelloWorld {
@StartDocument
public void executeInStartDocument(){
System.out.println("Hello World!!!\n");
}
@EndDocument
public void executeInEndDocument(){
System.out.println("Bye bye World!!!\n");
}
@StartElement
public void executeInStartElement(@CurrentBranch String currentBranch){
System.out.println(currentBranch);
System.out.println("Executing something in start element\n");
}
@EndElement
public void executeInEndElement(@CurrentBranch String currentBranch,@Body(tab=false, newLine=false) String body){
System.out.println(currentBranch);
if(body.length()!=0)
System.out.println(body);
System.out.println("Executing something in end element\n");
}
}
Keep attention at the parameters. We put some annotations in them to tell JColtrane which parameters we want to acces. It is smart enough to give us the right ones.
Some Conclusions
At this point, you can think: "These people think I am no smart, they put a specific example just to try convice me that JColtrane is good". The purpose of this litle example was just to give the reader a snapshot of the framework. We intend begining to answer 4 questions from the homesite's JColtrane:
- Why SAX doesn't have some default conditions and give me a easy way to create my own conditions, saving me from code a lot of annoying blocks if/else and making maintence easier?
- Why SAX doesn't keep past elements to help me, saving me work?
- Why, when using SAX, have I to extends a class (DefaultHandler), implementing methods with a lot of parameters, once I don't need all of them, or I even don't need all implemented methods?
- How do I make the XML parsing process extensible?
With the concepts presented in this section, we will go deeper in above questions in next sections to show how the framework can do the "dirty work". Try Basic Annotation Conditions
