Skip to main content

How to consume StrikeIron US Address Verification 5 in Apache Axis

No replies
danfds
Offline
Joined: 2009-05-18
Points: 0

To enhance the power and functionality of Java applications, it is very useful to be able to integrate them with other external applications or Web services as it can dramatically reduce the time required for software development and help deliver applications with maximum functionality.

For example, a CRM application developed in Java might likely need to verify existence and also correct customer addresses stored in the contact database, especially if it can be achieved using data available from the United States Post Office as the reference verification source. This way, when sending collateral, products, or anything else, you can save money by ensuring that a shipment actually gets there. Also, doing so can provide for much better and accurate customer data in general, and ultimately enable much better customer service. There is nothing more harmful to CRM efforts than incorrect and/or incomplete customer information.

In this article, we would like to create a simple Java console sample to demonstrate how easy it is to integrate with an external Web service like [URL="http://www.strikeiron.com/ProductDetail.aspx?p=437"]US Address Verfication Web services[/URL] within Java. This takes you only 5 minutes to complete.

Now let's start with the preparation.

1. Download and install the latest Java JRE from http://java.sun.com
2. Download latest Apache Axis libraries from: http://ws.apache.org/axis/. This library is very heplful for you to generate the first Java classes from a Web service WSDL, so you can save lots of time to develop it from scratch.
3. Find a web service that has ability to verify people's addresses. There are a few out there, but we are choosing a Web service from StrikeIron since it provides plenty of output information. In order to register, please visit the StrikeIron US Address Verification Web serivce at http://www.strikeiron.com/ProductDetail.aspx?p=437 to get a trial UserID and Password so you will be able to invoke the live Web service. StrikeIron also provides additional services to verify global addresses come from many countries if your customer addresses are outside US as well.

Next, there are 4 steps to do:

1. Install Java JRE and Axis libraries.
2. Generate the first Java classes from the StrikeIron web service WSDL: http://wsparam.strikeiron.com/USAddressVerification5?WSDL. This is a non SOAP Web service.
3. Start writing Java codes for the sample.
4. Run it.

Step 1: Install Apache Axis libraries.

Unzip the zip file downloaded from http://ws.apache.org/axis/ to a folder like C:\Axis14. That's it for the installation.

Step 2: Generate the proxy classes from the Web service to prepare for the invocation.

Create a bat file with the following content:

java -cp C:\Axis14\axis-bin-1_4\axis-1_4\lib\saaj.jar;C:\Downloads\axis-bin-1_4\axis-1_4\lib\wsdl4j-1.5.1.jar;C:\Downloads\axis-bin-1_4\axis-1_4\lib\jaxrpc.jar;C:\Downloads\axis-bin-1_4\axis-1_4\lib\commons-discovery-0.2.jar;C:\Downloads\axis-bin-1_4\axis-1_4\lib\axis.jar;C:\Downloads\axis-bin-1_4\axis-1_4\lib\commons-logging-1.0.4.jar org.apache.axis.wsdl.WSDL2Java -a http://wsparam.strikeiron.com/USAddressVerification5?WSDL
pause

In this bat file, we define a WSDL URI of the US Address Verification Web service as one of the options of WSDL2Java command. Later, you can change it to any WSDL URI from StrikeIron for other samples.
Save file to your project folder, i.e.: D:\Projects\USAddressAxisSample\GenClasses.bat
Run this file, all classes will be generated in this folder, stored in com folder. Notice option -a in the above command to tell the WSDL2Java create classes for all SOAP element references (including SOAP header references) in the WSDL file.

Step 3: Start writing Java Codes for the sample.
- Open Ecplise or any Java IDE tool. Create a console Java application and import all classes generated in "com" folder into this project.
- Add all files in unzip Axis folder such as C:\axis14\axis-1_4\lib\saaj.jar,... to project library paths.

- Create a new classes called SampleClient with the package is com.strikeiron.www.sample. Remember to replace the UserID and Password in the code with the one you have after your StrikeIron product registration.
Here is the code:

package com.strikeiron.sample;

import java.rmi.RemoteException;

import javax.xml.rpc.ServiceException;

import com.strikeiron.www.USAddressVerificationLocator;
import com.strikeiron.www.USAddressVerificationSoap;
import com.strikeiron.www.holders.SISubscriptionInfoHolder;
import com.strikeiron.www.holders.SIWsOutputOfUSAddressHolder;
import com.strikeiron.www.*;

public class SampleClient {

public static void main(String[] args) throws ServiceException, RemoteException {
/**
* This sample project demonstrates how to call the StrikeIron US Address Verification 5.0
* web service operation. To use this sample code, you will need a Registered StrikeIron Account. If you
* do not have a StrikeIron Registered Account, you can obtain one here: http://www.strikeiron.com/Register.aspx
*
*/

String userID = "userID@anysite.com";
String password = "your password";

String addressLine1 = "15501 Weston Parkway";
String addressLine2 = "Suite 150";
String cityStateZipCode = "Cary, NC 27513 USA";
CasingEnum casing = CasingEnum.UPPER;

/**
* When using Apache Axis 1.4 WSDL2Java to generate proxy classes for a web service definition, there will be a Locator
* class used to generate instances of a web service client object. For this web service the locator class name is
* USAddressVerificationLocator, and the web service client object - which contains methods for each web service operation
* described in the web service definition - is named USAddressVerificationSoap.
* Instances of each of these classes are defined and initialized below.
*/
USAddressVerificationLocator serviceLocator = new USAddressVerificationLocator(); //initialized using default constructor

USAddressVerificationSoap siService = serviceLocator.getUSAddressVerificationSoap();//initialized using service locator

/**
* The web service operation can now be called using the inputs declared above. Outputs are stored in holder objects,
* also defined above. Note that for simplicity, there is no error handling in this project. In a production environment,
* however, any web service request should be wrapped in a try-catch block with appropriate error handling.
*/
SIWsOutputOfUSAddressHolder holderResult = new SIWsOutputOfUSAddressHolder();
SISubscriptionInfoHolder licInfo = new SISubscriptionInfoHolder();

siService.verifyAddressUSA("",userID,password,addressLine1, addressLine2, cityStateZipCode, "", "", casing,holderResult,licInfo);

/**
* The web service output object contains two elements: ServiceResult, which contains the output data based on web service inputs,
* and ServiceStatus, which contains a numeric status code and description indicating the success/failure status of the web service
* request. You can make the following assumptions about the StatusNbr field within ServiceStatus for any StrikeIron web service:
* -> 200-299: Operation completed successfully (data found, etc)
* -> 300-399: Operation completed with non-fatal error (no data found, etc)
* -> 400-499: Operation failed due to invalid input
* -> 500+: Operation failed due to unexpected internal error, contact support@strikeiron.com
*
* The output fields from the web service are now displayed to the console. Note that not all output fields from ServiceResult are included.
* For more information on the data elements returned by StrikeIron US Address Verification 5.0, refer to the product description page provided
* above.
*/
System.out.println("WEB SERVICE OUTPUT:\n");
System.out.println("Remaining hits: " + licInfo.value.getRemainingHits()+ "\n");
System.out.println("Service status: " + holderResult.value.getServiceStatus().getStatusDescription() + "\n");
System.out.println("AddressLine1: " + holderResult.value.getServiceResult().getAddressLine1());
System.out.println("City: " + holderResult.value.getServiceResult().getCity());
System.out.println("Province: " + holderResult.value.getServiceResult().getState());
System.out.println("PostalCode: " + holderResult.value.getServiceResult().getZIPCode());
System.out.println("Latitude: " + holderResult.value.getServiceResult().getGeoCode().getLatitude());
System.out.println("Longitude: " + holderResult.value.getServiceResult().getGeoCode().getLongitude());
}

}

The holderResult and licInfo object is created to hold the main output data and subscription info returned from the Web service.

Step 4:
Build and Run the console application. You will see the results in the console window including the Longitude and Latitude of the address.

Good luck and enjoy programming!

Dan

References:
1. StrikeIron US Address Verification Web services 5.0 at http://www.strikeiron.com/ProductDetail.aspx?p=437
2. Java: http://java.sun.com
3. Apache Web service Axis library: http://ws.apache.org/axis/