Learning Curve Series Journal 7
June 22nd, 2006 by WalterExploring Web Services, Part 2: The E-Mail Validation Service
In an earlier Learning Curve journal I experimented with configuring Google’s spell checker web service, knowing that web services are a powerful tool for building many kinds of web applications. I discovered that configuring them within the Creator IDE is easy through its menus and dialog boxes.
Contents
- The Plan
- Non-Compliance (Why I Couldn’t Use the National Weather Web Service)
- Xmethods: A Resource for Finding Web Services
- The E-Mail Address Validation Web Services I Chose Instead
- Step 1: Add a Web Service to the IDE
- Step 2: Test the Method
- Step 3: Build the Page-the JSP
- Step 4: Build the Page-the Page Bean
- Step 5: Working with Objects
- Conclusion and Job Opportunities
- Next time…
The Plan
For this article I want to dive into web services at a more serious level than the Google spell checker that I used to just get familiar with web services. Although some web services are built in to the Java Studio Creator IDE, I want to find an outside web service and try out the install process, which will also allow me to explore what references are available to help me choose a web service for a particular application. I also want to start using a web service to explore working with objects, as many web services return more complex data structures over the simple spell checker I explored earlier, which only returns a string.
Non-Compliance (Why I Couldn’t Use the National Weather Web Service)
In the last installment I wrote that I planned to install a web service by the National Weather Service to obtain weather reports. I tried, but in the process of doing so I found that their web service is non-WS-I compliant.
What does WS-I non-compliance mean? Well, when I tried this web service it returned non-standard SOAP messages that did not work in the “test-method” functionality of the IDE (as I’ll show below).
WS-I is an “open industry organization chartered to promote web services interoperability across platforms, operating systems and programming languages,” as explained by the organization that controls this standard, WS-I (www.ws-i.org).
The power of the Java Studio Creator IDE and other web application development tools is that they rely on industry standards; in fact they are built on them and depend on certainties guaranteed by the standards boards. There is much benefit in that these tools are built on the J2EE specification (as discussed in Part I) and the same principle applies to web services and WS-I compliance. The standards developed by WS-I go far beyond the scope of any one IDE or programming technology, including Java, so it makes sense to stay away from non-compliant web services.
It is possible that I could have gotten the weather web service configured, with some difficulty, but I chose something else that was applicable to my business.
Xmethods: A Resource for Finding Web Services
In searching for something else to try, I found a site - www.xmethids.com - that lists over 400 web services. Besides services that provide or calculate exchange rates, stock quotes, weather, news, and sports, some of the great things they do for you include:
- Search over 67,000 recipes
- Get up-to-the-minute World Cup scores
- Send instant messages to four major services
- Search for nutrient content of over 7300 foods
- And, if you’re inclined, see what’s on TV in Iceland!
The E-Mail Address Validation Web Services I Chose Instead
On Xmethods I found a useful web service that checks and validates an e-mail address for allowing site visitors to join e-mail lists, submit forms, and such, to try. In my business, I’ve discovered that even with JavaScript validating my forms, visitors can still get around it by disabling JavaScript in their browse. I often find non-valid e-mail addresses making it through my forms.
The e-mail verifier I found is by CDYNE. It checks the validity of an e-mail address by querying its mail server in real time.
Step 1: Add a Web Service to the IDE
Here’s how to add the e-mail verifier to the Java Studio Creator IDE. First, I open the IDE and right-click on Web Services in the Servers window, and am presented with the option to Add Web Service. A new dialog box opens (Figure 1), which allows me to not only install a Web Service but also obtain information about it.
Figure 1: Adding a Web Service |
I obtained CDYNE’s WSDL file by visiting their site, though I could have copied it directly from Xmethods.
I insert this link to the WSDL file into the URL field in the Add Web Service dialog box:
http://ws.cdyne.com/emailverify/Emailvernotestemail.asmx?wsdl
Then I click the Get Web Service Information button to obtain details on the methods available. This provides me with a lot of information about this e-mail verifier web service, including the ability to test its methods, but I’ll do that in the next step. For now, I just click the Add button to add this web service to the list of web services available in the IDE, as shown in Figure 1, above.
After clicking the Add button, my Servers window now lists this web Service as EmailVerNoTestEmail under the node Web Services. I can further expand this node to see that it contains four methods: verifyMXRecord, advancedVerifyEmail, verifyEmail and returnCodes (also called “Operations” in Web services language). For this discussion, I’ll use the verifyEmail method, which is similar to the advancedVerifyEmail method, except that it defaults to a timeout period, so you don’t need to pass its variable.
Step 2: Test the Method
A great feature available in the Servers window is that I can right click any method name and choose Test Method. As shown in Figure 2, I get a visual interface that lets me enter my variables for the method, and then view the results returned by the web service, all without creating a form or writing code. It also tells me about the variables returned: two strings and an integer in this case. In looking closely, these variables are actually returned in an object called ReturnIndicator.
Note: CDYNE, the author of this web service, allows me to test it by leaving the licenseKey field blank. I can later purchase a subscription to it and obtain a license key.
Figure 2: Test Web Service Method Window |
I can also get more detailed information about the methods and its variables by viewing its Properties window (in the upper right corner of the IDE, by default). To do so, I click on the VerifyEmail method in the Servers window, and the Properties pane then shows me the method information and parameters (Figure 3):
Figure 3: Viewing Method Parameters |
Note: the Method returns an Object ReturnIndicator. Clicking the [?] button displays type of elements contained within the object. The Properties window also lets me know that the variables I need to provide the web service are strings (email and licenseKey). The method advancedVerifyEmail also accepts an integer timeout.
One final note: After I install the web service in my project (by dragging it onto the design pane as described in Part I), I can view even more information by expanding its node in the Projects window (located in the middle right of the IDE by default). There is more information here than I’ll ever want to know. For example, I can click on AdvancedVerifyEmail.class and view information about its fields (email, licenseKey and timeout), and also click on them to view additional information in the Properties window.
Figure 4: Project Window - The Project window also provides very |
Step 3: Build the Page-the JSP
Now that I have some information about the web service and what kind of variables it returns I can build the page. I started by setting it up in the JavaServer page, as shown in Figure 5, below.
Figure 5: Building the Page |
Note the following:
I drag the web service (called emailVerNoTestEmail in the Servers window) onto the design canvas. The Web service, emailVerNoTestEmailClient1, can also be seen in the Outline window. I’ll work with this name later in the Page Bean.
To try this project, build the page as shown in Figure 5 by dragging Text Field and Static Text components from the Palette onto the page. Label the Text Field ID’s as follows in the Properties window:
- Enter an E-Mail Address is labeled
email - Server is labeled
resultServer - Response is labeled
resultResponse - Response Code is labeled
resultCode
Step 4: Building the Page-the Page Bean
The next step is to write Java that will execute when an e-mail address is submitted. To do so, I double click on the Verify E-Mail button. This puts me right into the Page Bean inside of the method that will execute when this button is pressed at runtime. The code I enter is shown in Code Sample 1 below.
public String button1_action() {
String emailCheck = null;
ReturnIndicator mySearchResult = null;
String license = "0";
int myCode = 0;
if (this.email.getValue() != null) {
emailCheck = (String)this.email.getValue();
try {
mySearchResult =
emailVerNoTestEmailClient1.verifyEmail(emailCheck, license);
String myServer = mySearchResult.getLastMailServer();
if (myServer != "") {
resultServer.setValue(myServer);
}
else{
resultServer.setValue("No Results Found");
}
String myResponse = mySearchResult.getResponseText();
if (myResponse != "") {
resultResponse.setValue(myResponse);
}
else{
resultResponse.setValue("No Results Found");
}
myCode = mySearchResult.getResponseCode();
resultCode.setValue(new Integer(myCode));
}
catch (Exception e) {
log("Remote Connect Failure", e);
throw new FacesException(e);
}
}
else{
log("E-mail address not entered");
email.setValue("Please enter your e-mail address");
}
return null;
}
Code Example 1: Code executed when an e-mail address is submitted
But I discovered a problem here:
Creator doesn’t recognize the ReturnIndicator object, and generates an error (a red “x” next to the line of code) when I type ReturnIndicator mySearchResult = null;.
The reason for this is that I need to add an import statement. But Creator has another great feature to help me here — I can right click in the code and select “Fix Imports”. Creator then checks my code and added the following import statement:
import webservice.emailvernotestemail.ReturnIndicator;
The red “x” next to the line of code then goes away. Please see the side-bar for the reason behind needing to import this package.
Continuing on - much of the code I enter in Code Sample 1 above was explained in my previous article, Part I, but to review a few of the highlights here:
I build the call to the web service by using code completion. As I drag the web service onto the editing area, the IDE tells me the name it will refer to it as: emailVerNoTestEmailClient1. As I type this in, code completion lets me build the rest of the string.
I use a try/catch statements to provide some level of error checking. More error checking can be added later. The call to the web service MUST be within a try/catch block because the actual method call throws a java.rmi.RemoteException.
Step 5: Working with Objects
As I mentioned earlier, ReturnIndicator is of type java.lang.Object. The object includes several methods that lets me extract its information. In this case, ReturnIndicator returns two strings and one integer that I then populate in my form as a response. The methods I use to produce this information are: getLastMailServer(), getResponseText(), and getResponseCode().
How do I discover these methods? Again, code completion comes to the rescue! In my third block of code above-after declaring my web service and verifying that an e-mail addresse is passed, I start typing:
String myServer = mySearchResult.
Code Example 2
And after the period, code completion shows me the three methods named above (as well as some other information that I need not be concerned with at the moment).
Note: To work with code completion faster (instead of waiting for it to “wake-up” after entering the period), hit control+spacebar.
I continue with code completion to produce, in the try/catch block:
String myServer = mySearchResult.getLastMailServer();
Code Example 3
Code completion also tells me that it produces a result of type String, so I need to declare it as I did above, and then I can populate the ResultServer text box in my form with the result as follows:
ResultServer.setValue(myServer);
Code Example 4
The same is true for obtaining the response string from the ReturnIndicator object
String myResponse = mySearchResult.getResponseText();
Code Example 5
Followed by resultResponse.setValue(myResponse); will populate the text box in my form.
Finally, I need to retrieve the integer result-a code that I can perform further calculations on to tell me about the results of checking an e-mail address. Using code completion, I call the getResponseCode() method as follows
myCode = mySearchResult.getResponseCode();
Code Example 6
Note: myCode has already been defined above in the declaration int myCode = 0; It could have instead been declared here as
int myCode = mySearchResult.getResponseCode();
Code Example 7
Then I populate my “Response Code” text field as follows:
resultCode.setValue(new Integer(myCode));
Code Example 8
setValue() is a method itself, and it only accepts objects (which includes Strings as they are considered objects as well). But in this case I want to use setValue() to work on an integer. So then I must use Integer as an Object wrapper for this primitive type int. I tried this statement without this Object wrapper and got an error because the Java Studio Creator IDE informs me that it can’t find the symbol resultCode with a method setValue() that takes an integer.
Side Note
When building my application, I discovered in my Java that Creator had automatically added a number of package imports, including this in response to dragging the Web service onto the design canvas:
import webservice.emailvernotestemail.emailvernotestemail.EmailVerNoTestEmailClient;
However, when I built my code, I got an in-line error because one additional package was missing. This was easily fixed by right-clicking in my code, and selecting “Fix Imports”. But why do both packages need to be imported, and why did Creator initially import only one?
I learned that this is because Java Studio Creator 2 uses a new naming convention that allows compatibility with more complex implementations. For example, I may want multiple Web services to with the same name but on different ports. I was able to ask David Botterill, the Java Studio Creator Evangelist, to further clarify the logic behind this. He responded:
“If we were doing visual design, Creator inserts the necessary imports for objects you’ve added to the designer. While working with the Java source, Creator can do some things automatically. But the “import” is controlled by the underlying NetBeans platform. NetBeans can not make guesses about what packages (import) you want to include just by you typing in class names. A common example of this is “Date”. If you type “Date”, NetBeans doesn’t know if you want the java.util.Date or the java.sql.Date. A developer could program using full package specifications like webservice.emailvernotestemail.ReturnIndicator but this requires too much typing and also requires a developer to memorize package names. A developer can do many things to work through this issue in NetBeans. I think the most common usage pattern is to find out the Class name and use that in the declaration. Then the developer uses the very nice NetBeans feature “Fix imports” found by right-clicking on the Java source. “Fix Imports” adds necessary import statements and removes unused import statements. Also, “Fix Imports” uses the full package name for the class, java.util.Date instead of specifying the entire package, java.util.*. This makes the class more readable and thus easier to maintian. “Fix Imports” also provides a name clash resolver. If the developer had typed “Date”, a dialog would show up allowing the developer to choose between java.util.Date and java.sql.Date.”
Side Note: David Botterill
Conclusion and Job Opportunities
That’s a pretty comprehensive look at web services and their power and feasibility within the Java Studio Creator IDE. Web services are fun to work with and can do a lot of work for you with minimal coding. I suspect we’ll be seeing web services take an even more prominent role in our lives in the near future as more organizations start porting their offerings over to them. That’s a hint by the way, as they’ll soon be looking for developers. I’m still finding companies doing things the old way-an MLS real estate listing service that provides my client daily MLS feeds via automated FTP an example-and they’re going to be looking for web service developers very soon! The Java Studio Creator IDE won’t help with Web Services application development, but its big brother Java Studio Enterprise will, and so will Sun’s NetBeans IDE.
I would like to give special thanks to David Botterill with Sun Engineering for his assistance in helping me configure these web services.
Next Time…
In the next two installations of the Learning Curve I’ll explore database integration with the bundled databases server, MySQL and Microsoft SQL Server.
More Developer Resources
For more tech tips, articles, and expert advice for developers, visit the Java Studio Creator developer resources on the Sun Developer Network (SDN) at /jscreator/.
Tags: Creator, IDE, Java, Sun, Technology
