This tutorial is no longer supported and may include content that is incorrect or invalid.
Overview
The purpose of this tutorial is to help developers create an On-Premise REST Web Service using the Loqate Local API in Java. The resulting web service response is in both XML and JSON format. A sample web service test client is also provided.
Tutorial Java Source Code
All sample Java source code for this tutorial is summarized in Table 1 below. The source code can be seen by following the links shown in that table. The Java packages as used in this tutorial are also listed in the same table.
| Java Package | Java Class (source code) |
| com.loqate.ws.rest.core | LqtLocalAPICaller.java |
| com.loqate.ws.rest.service | LqtLocalAPIService.java |
| LqtWebQueryRecord.java | |
| com.loqate.ws.rest.client | LqtRestTestClient.java |
Table 1: Sample Java Source Code for this Tutorial
The same sample Java source code files needed to run this tutorial are available for download in the link below.
Download the Tutorial Source Code files here (zip)
Requirements
The following software is required to complete this tutorial:
- 1 – Loqate Local API
- For developing this tutorial the Loqate Local API version used was 2012Q2.0. It is assumed the user has installed the Local API in the directory C:\Data1. It is also assumed that Loqate’s Global Knowledge Repository is installed in C:\Data1\data. If a different directory location has been used to install the Loqate Local API, then that installation path should be used when defining installation path variables in the sample code.</> If the development will be done in a 64-bit server, it is recommended to install the 64-bit version of the Local API.
- 2 – NetBeans IDE 7.1.1 ( or later ) including Apache Tomcat 7.0.22.
- This tutorial assumes the user has installed the Apache Tomcat that comes bundled with the NetBeans IDE. The NetBeans Download Bundle used to develop and test this tutorial was the “Java EE” version provided by NetBeans in their website: http://netbeans.org/downloads/index.html.
Note: alternatively, the Apache Tomcat Servlet/JSP container, the Oracle’s Glassfish server or a compliant J2EE 6 container can be installed separately and used successfully.
Configuration
Path Configuration
Please add to the PATH user variable in your Windows Environment the following:
- The Loqate installation directory
- The Loqate installation /data directory
- The Loqate Java library lqtjava.dll
The Loqate Java library is available in the Loqate installation directory. Failing to add this library will result in error messages when trying to run, for example, the test client (LqtRestTestClient.java).
Creating a New NetBeans Project
Open NetBeans 7.1.1 by clicking in the NetBeans icon in your desktop or “All Programs” list. After NetBeans is open, please select “File” -> “New Project”. The “New Project” window will be displayed. Select “Java Web” and then “Web Application”, as shown below.
Figure 1: NetBeans New Web Application Project
Please click the “Next” button. NetBeans will briefly display a message while activating Java web and J2EE. Afterwards it will display the window shown below.
Figure 2: NetBeans Project Name and Location Window
At this point is recommended to enter a new project name. The project name we will use for this tutorial is “LqtWSRestApplication”. That is the only field modified in this window, as show below. We leave on the check mark for “Set as Main Project”.
Figure 3: NetBeans Project Name and Location Settings
Please click “Next”. The following window will be displayed.
Figure 4: NetBeans Server and Settings Window
In the “Server” field, select “Apache Tomcat 7.0.22.0” from the scroll-down list. Leave the rest of the default options. The resulting window will look as shown below.
Figure 5: NetBeans Server and Settings Choices
Please click the “Next” button. The window shown below will be displayed.
Figure 6: NetBeans Frameworks Window
Leave that window unchanged and click the “Finish” button. NetBeans will create a new project and display the window shown below.
Figure 7: NetBeans New Empty Web Application Project
Please expand the folders of the “LqtWSRestApplication” by clicking on the “+” sign to the left of that project. Multiple folders will be displayed as shown below.
Figure 8: NetBeans Project folders
Select the “Source Packages” folder. Right-click and select “New” -> “Java Package…”. The following window will be displayed.
Figure 9: NetBeans New Package Name and Location Window
In the “Package Name” field enter “com.loqate.ws.rest.core”, as shown below.
Figure 10: NetBeans New Package Name
Please click the “Finish” button.
Please repeat the same steps to create two more Java packages, com.loqate.ws.rest.service and com.loqate.ws.rest.client. After that three Java packages should be displayed, as shown below.
Figure 11: NetBeans New Packages Created
Next it is necessary to add the required Java classes to each Java package. All Java packages and corresponding Java source code are summarized in Table 1 below, which we display again here for convenience. The code for each Java class can be accessed by clicking in the links below.
| Java Package | Java Class (source code) |
| com.loqate.ws.rest.core | LqtLocalAPICaller.java |
| com.loqate.ws.rest.service | LqtLocalAPIService.java |
| LqtWebQueryRecord.java | |
| com.loqate.ws.rest.client | LqtRestTestClient.java |
Table 1: Sample Java Source Code for this Tutorial
To add the LqtLocalAPICaller.java to the com.loqate.ws.rest.core package, select the com.loqate.ws.rest.core package, right-click and then select “New”->”Java Class…”. The following window will be displayed.
Figure 12: NetBeans New Java Class Window
In the Class Name field enter the Java class name “LqtLocalAPICaller”. The window will look as shown below.
Figure 13: NetBeans New Java Class Name
Click the “Finish” button. NetBeans will show an empty template class as shown below.
Figure 14: NetBeans New Java Class Empty Template
Please replace all the template contents by the source code from the LqtLocalAPICaller.java file provided in this tutorial. This is done by simply cut-and-paste. Select the source code and paste it on top of the template code. Then click “File”->”Save”. As shown in the figure below, red lines indicating a compilation problem will be displayed. This can be easily solved by adding the Loqate jar file (loqate.jar) to the project, which is explained next.
Figure 15: NetBeans Replacing template with Tutorial Sample Code
To add the loqate.jar file to the project, please select the project name, LqtWSRestApplication, right-click and then select “Properties”. The Project Properties window will open. There select “Libraries”. The “Compile” tab should be displayed. Click on the “Add JAR/folder” button. Browse to the location of your loqate.jar library, which is located in the Loqate installation directory. Select the loqate.jar file and click “Open”. The loqate.jar file will then show as added in the “Compile” tab, as shown below.
Figure 16: Adding loqate.jar file to Project
While in the “Libraries” window go ahead and add two libraries. Click on “Add Library…”. The “Add Library” window will be displayed. From the list of “Available Libraries” select “JAX-RS 1.1”, press Ctrl key and select the library “Jersey 1.8 (JAX-RS RI)”. Click the “Add Library” button. The “Compile” tab should look as shown below.
Figure 17: Adding JAX-RS and Jersery Libraries to Project
Please click “OK”. Most of the red marks indicating compilation problem should be removed automatically. The red marks still displayed correspond to the LqtWebQueryRecord class which we will add next.
Next it is required to add the Java classes LqtWebQueryRecord.java and LqtLocalAPIService.java to the com.loqate.ws.rest.service package. This can be done using the same approach used earlier to add the LqtLocalAPICaller.java, adding both also as Java classes. Please be careful that the corresponding source code is pasted in the correct class. This time it is not required to add the libraries as they have been added earlier. However, when you click “Save” the window shown below will be displayed.
Figure 18: NetBeans Default REST Resources Configuration Window
This default selection has to be modified. Please select the option “Create default Jersey REST servlet adaptor in web.xml.” The window should now look as shown below.
Figure 19: NetBeans REST Resources Configuration Choices
Please click the “OK” button.
Finally it is necessary to add the client class LqtRestTestClient.java into the com.loqate.ws.rest.client package. To do this we follow the same approach, adding a Java Class to that package similar to how LqtLocalAPICaller.java was added earlier to its corresponding package. Save the project by selecting “File”->”Save”.
Building and Running the project
Select the project name, LqtWSRestApplication”, and from the top menu select “Run”->”Clean and Build Main Project”. Afterwards right-click on the project name and select “Deploy”. Click on the “Output” tab on the lower part of the Netbeans window and notice the Apache Tomcat messages and application messages displayed, which are useful for debugging purposes. The “LqtWSRestApplication” tab should display a “BUILD SUCCESSFULL” message. Two Apache tomcat tabs should open, one of them should not display any error messages and one of the will display a group of Apache messages ending on a message similar to the message shown below:
…
Jun 19, 2012 5:37:08 PM com.sun.jersey.server.impl.application.WebApplicationImpl _initiate
INFO: Initiating Jersey application, version ‘Jersey: 1.8 06/24/2011 12:17 PM’
Jun 19, 2012 5:37:09 PM org.apache.catalina.util.LifecycleBase start
INFO: The start() method was called on component [StandardEngine[Catalina].StandardHost[localhost].StandardContext[/LqtWSRestApplication]] after start() had already been called. The second call will be ignored.
As no errors are displayed at this time the web service is up and running and could be tested from a browser if desired. However we can also use the test client to test our service, as explained in the next section.
The Figure below shows the two Apache tabs and the LqtWSRestApplication (run-deploy) tab.
Figure 20: NetBeans Project Window after Deploying the Project to Apache Tomcat
Testing the Loqate On-Premise REST Web Service
The REST web service can be tested using a browser and also using the given test client. The two options are explained in the following sections.
Testing the Web Service Using a Browser
In this case the user can open a browser and enter the following URL query:
http://localhost:8084/LqtWSRestApplication/resources/query/run?organization=Loqate%20Inc.&address=1111%20Bayhill%20Drive&locality=San%20Bruno&country=USA&administrativeArea=CA&postalCode=94066
To test from a different server than from where Apache is running please provide the name of the ost running the web service instead of “localhost”.
The web service should return as a result the LqtWebQueryRecord information in an XML format, as shown in the Figure below.
Figure 21: Testing Loqate On-Premise REST Web Service in a browser
Running the Web Service client
The test client provided allows the user to see the web service response in both XML and JSON format. To run the test client in NetBeans right-click on the test client java class, LqtRestTestClient.java, and then select “Run File…”. The “LqtWSRestApplication(run)” tab at the bottom of the NetBeans window should display the following output:
run:
XML Format Response:
<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?><lqtWebQueryRecords><lqtWebQueryRecord><AVC>V44-I55-P6-100</AVC><address1>Loqate Inc</address1><address2>1111 Bayhill Dr</address2><administrativeArea>CA</administrativeArea><country>United States Of America</country><locality>San Bruno</locality><organization>Loqate Inc</organization><postalCode>94066</postalCode></lqtWebQueryRecord></lqtWebQueryRecords>
*********************
JSON Format Response:
[{“locality”:”San Bruno”,”organization”:”Loqate Inc”,”avc”:”V44-I55-P6-100″,”address1″:”Loqate Inc”,”address2″:”1111 Bayhill Dr”,”postalCode”:”94066″,”administrativeArea”:”CA”,”country”:”United States Of America”}]
*********************
BUILD SUCCESSFUL (total time: 2 seconds)
The NetBeans window will look as shown below.
Figure 22: Testing Loqate On-Premise REST Web Service with sample Test Client
The Apache Tomcat tabs should not display any exception. The result displayed demonstrates the web service is indeed running and able to return an address query result in both XML and JSON formats, depending on the format selected by the client.