Introduction
It is relatively easy to build Java servlets that can parse and return XML documents with the help of the BorlandXML toolset found in JBuilder Developer and Enterprise editions. BorlandXML provides s a mechanism for extracting data from XML documents and creating XML documents using JavaBeans. In this article, we will use the BorlandXML toolset to build a servlet based web service that intercepts XML requests from the Internet and returns a XML response.
Some Housekeeping
As you are already aware, web services are used to send and receive XML files across the Internet. Let's look at an example. Assume that we are a product distributor. Aside from providing a web site for our customers, we want to build a facility to allow retail Point of Sale systems to query our product database over the web in order to check inventory quantities. To accomplish this task we're going to build a web service. For the web service we'll need two XML files: request.xml and response.xml.
request.xml
<?xml version="1.0"?> <StockCheckRequest$> <ProductNumber>0785263268</ProductNumber> </StockCheckRequest>
The request.xml file will be used by the POS system to send us the product numbers. Without going into a long discourse on XML, suffice it to say, much like HTML, XML files are made up of elements (or tags) and data. Tags are denoted by the “<” “>” braces. Like HTML, XML tags are nested within one another. Also like HTML, XML tags begin contain a label between the braces that describes the information that follows. They end with a tag that “/” before the label. Unlike the typical HTML file, XML tags typically have custom labels that are either defined by an application (read web service) or in some cases an agreed upon standard.
Let's examine the structure of request.xml. It contains a set of XML tags called StockCheckRequest. Within the StockCheckRequest tags there is a set of tags for ProductNumber. It is between these tags that we define the data (in this case a product number) that we want to send.
Note: we can define multiple ProductNumber tags within the StockCheckRequest tag as long as we program for it.
Now let's take a look at the response.xml file.
response.xml
<?xml version="1.0"?> <StockCheckResponse> <Header> <FromCompany> </FromCompany> <FromPerson> </FromPerson> <FromEmail> </FromEmail> <SentDate> </SentDate> </Header> <Product> <ProductNumber> </ProductNumber> <Title> </Title> <Description> </Description> <Stock> <OnHand> </OnHand> <OnOrder> </OnOrder> </Stock> <PackQuantity> </PackQuantity> <Price> </Price> </Product> </StockCheckResponse>
response.xml file is the file that we will be sending back to the retail POS system. As you can see it contains a set of tags called StockCheckResponse. Within this set of tags there is a set of tags called Header that contains information about our company. Next we have a set of Product tags that tell the POS system about the product they requested.
Now that we've established our XML, let's take a look at our project.
bdn.webservices
I assume you are already familiar with building projects, servlets, etc. in JBuilder. If not, you should familiarize yourself with the JBuilder environment before proceeding. That being said, we're creating a new project in JBuilder called bdn.webservices. We're going to add our XML files, request.xml and response.xml, to the project. Now let's have some fun.
In order to use our XML files within Java, we need a way to translate them. BorlandXML contains some handy tools for manipulating XML files. The first tool we'll look at is the DTD (Document Type Definition) generator. The purpose of a DTD is to define the XML's document structure with a list of legal elements. In order for applications to parse XML files, there must be a DTD associated with the file.
Step 1
To activate the generator we select right click the request.xml file in JBuilder's Project pane (see above) and select the Generate DTD menu option. We will see the XML to DTD Wizard window:
Click OK to generate the request.dtd file.
Step 2
Now that we've generated a DTD file, we can use another handy BorlandXML tool: the Java generator. When you right click on request.dtd in the Project pane, you'll see the following:
Select Generate Java. You should see the Databinding Wizard – Step 1 of 2 window.
Step 3
In this window, you have to option of selecting the Databinding framework: either BorlandXML or Castor. For this project, we're going to use BorlandXML. Select BorlandXML and click Next >. You will now see the Databinding Wizard – Step 2 of 2 window.
Step 4
This window allows us to select which DTD element we want to generate a Java class for. Refer back to our request.xml file. The root element for the XML file is StockCheckRequest. ProductNumber is a child element. Therefore we want to select StockCheckRequest and click Finish.
Looking at the Project pane, you can see that we now have new JavaBean objects: StockCheckRequest.java and ProductNumber.java. If you look at the Structure pane (found on the bottom left side of the JBuilder window), you'll notice lots of errors. These errors can be resolved by building the project.
Next, we'll need to repeat steps 1-4 for the response.xml file. Remember to select the StockCheckResponse element when generating the Java source code. Build the project to get rid of errors.
Now that we've created some JavaBeans we're going to build a servlet called StockCheck.java.
StockCheck.java
I'm going to assume that you are already familiar with building servlets in JBuilder. If not, I suggest that you read through the JBuilder help files. Let's take a look at the code.
package bdn_webservice;
import javax.servlet.*;
import javax.servlet.http.*;
import java.io.*;
import java.util.*;
import java.text.*;
public class StockCheck
extends HttpServlet {
// global variables
private static final String CONTENT_TYPE = "text/html";
String ProductStr;
StringBuffer instr;
public void init() throws ServletException {
}
//Process the HTTP Get request
public void doPost(HttpServletRequest request, HttpServletResponse response) throws
ServletException, IOException {
StockCheckRequest scRequest = new StockCheckRequest();
scRequest.unmarshal(request.getInputStream());
ProductStr = scRequest.getProductNumberText();
StockCheckResponse scResponse = new StockCheckResponse();
Header header = new Header();
header.setFromCompanyText("ACME Stuff Distributors, Inc.");
header.setFromEmailText("tech_dude@yahoo.com");
header.setFromPersonText("Rick Proctor");
SimpleDateFormat sf = new SimpleDateFormat("yyyyMMdd");
java.util.Date date = java.util.Calendar.getInstance().getTime();
header.setSentDateText(sf.format(date));
scResponse.setHeader(header);
Product product = new Product();
product.setDescriptionText("product description");
product.setPackQuantityText("12");
product.setPriceText("24.99");
product.setProductNumberText(ProductStr);
product.setTitleText("ACME Thing");
scResponse.setProduct(product);
response.setContentType(CONTENT_TYPE);
PrintWriter out = response.getWriter();
scResponse.marshal(out);
}
public void doGet(HttpServletRequest request, HttpServletResponse response) throws
ServletException, IOException {
}
//Clean up resources
public void destroy() {
}
}
Take a look at the doPost() method. This method will be executed when a calling program sends a request.xml file to the servlet (we will see an example of this a little later). In the doPost() method we start by creating an instance of the StockCheckRequest object (see the request.xml section) called scRequest. Next we call the scRequest.unmarshal() method, passing an inputStream() object request...the request object is passed to the doPost() method as an input variable.
Note: BorlandXML uses a “marshalling framework” to convert XML documents. To turn XML into JavaBean objects use the unmarshal() method. To convert JavaBean objects to XML use the marshal() method. For more information see the JBuilder help documentation.
Now that we've converted the request.xml document, we can extract the ProductNumber field. In this case there are two methods that we can choose. The first method is getProductNumber(). This method returns a ProductNumber object. The second method getProductNumberText() returns a String object containing the ProductNumber data. In this case, we'll use the second method.
Building response.xml
Now, that we've received and parsed through the request.xml file, it's time to build and send a response. In the real world, we'd probably validate the ProductNumber field and bounce it against a database in order to retrieve information about the product. This is only an article, not the real world, so we'll just plug the data in.
The first thing we do is instantiate a StockCheckResponse object scResponse. This object will correspond to our response.xml file. The response.xml file we defined earlier had 3 levels of elements. At the top, we defined StockCheckResponse. Next we defined a Header element with detail elements underneath. Finally, we defined a Product element, with detail elements under it.
We instantiate a Header object header. Next, we call the set…Text() methods to load data into our header object. We call the scResponse.setHeader() method passing the header object. We instantiate a Product object product and call its set…Text() methods to load product specific data. Afterwards we call the scResponse.setProduct()method passing the product object.
Now that we've built a StockCheckResponse object, we need to convert it to an XML document and send the XML as a response. One method of accomplishing this task is to instantiate a PrintWriter object called out. This will create an output stream for us to write the XML file to. Next we call the marshal() method of our scResponse object using out. As mentioned earlier, the marshal() method converts our Javabean object to XML.
Congratulations. If you got this far, you've now converted a servlet into a web service. Now that we've built a web service, how do we test it? Let's take a quick look at a java class, TestStock.java, we can use to test our web service.
TestStock.java
package bdn_webservice;
import java.net.*;
import java.io.*;
public class TestStock {
public static void main(String[] args) {
HttpURLConnection connection;
URL url;
FileInputStream in;
InputStreamReader isr;
StringBuffer data = new StringBuffer();
try {
in = new FileInputStream("request.xml");
isr = new InputStreamReader(in);
int c;
while((c=isr.read())!=-1) {
data.append((char) c);
}
isr.close();
in.close();
url = new URL("http://localhost:8080/WebServiceMod/stockcheck");
connection = (HttpURLConnection) url.openConnection();
connection.setDoOutput(true);
connection.setDoInput(true);
connection.setUseCaches(false);
OutputStream out = connection.getOutputStream();
String queryString = data.toString();
System.out.println(queryString);
out.write(queryString.getBytes());
out.close();
InputStream in1 = connection.getInputStream();
isr = new InputStreamReader(in1);
StringBuffer buffer = new StringBuffer();
try {
int letter = 0;
while ( (letter = isr.read()) != -1) {
buffer.append( (char) letter);
System.out.print((char) letter);
}
}
catch (Exception e) {
System.out.println("Cannot read from URL" +
e.toString()); }
finally {
try {
isr.close();
}
catch (IOException io) {
System.out.println("Error closing URLReader!");
}
}
connection.disconnect();
}
catch (Exception e) {
System.out.println(e);
}
}
}
As you can see, TestStock.java does the following:
- Reads the request.xml file
- Establishes a Http connection with the StockCheck servlet
- Writes to request.xml file to the Http connection
- Reads the response.xml file from Http connection
- Writes the response.xml file to the console.
Now let's run our example. Outside of JBuilder we would fire up an application server such as Tomcat, make sure the StockCheck servlet was loaded, and then fire up the TestStock class. Since we're running this example in JBuilder, we'll do it a little differently. To start up Tomcat all we need to do is right click on The StockCheck tab, select Web Run from the menu and select use StockCheck. We will see something like this:
Now that our web service has started, we can execute the TestStock class. Right click the TestStock tab, and select Run using defaults. You should see the following results:
Looking at the highlighted areas in JBuilder's message pane, it is easy to see that we sent a request to the servlet. The servlet returned a response containing the information we wanted.
Conclusion
With JBuilder's BorlandXML tools, it is easy to turn a servlet into a web service. BorlandXML allows you to take a XML file, convert it to a DTD (Data Type Definition) file, and then create JavaBeans. Using the getters and setters, you can read data from an inbound XML file and send outbound data via XML tags. I hope this article sparks your imagination on ways you can convert your own servlets into a web service.
