Using Java Server Pages (back to all tutorials)

You can use Java Server Pages (JSP) to quickly build a simple web application. It is assumed that you already understand how to build and deploy web applications for your favorite servlet container; however, the SDK (source distribution) does include several examples, including the jsp-map-example, that demonstrate building a web application.

1. Step 1: Writing page.jsp

   You can incorporate location from Veriplace into a JSP page very easily using the Veriplace tag library:

   The setup tag configures an instance of com.veriplace.web.VeriplaceState, which is used behind the scenes to manage callbacks, redirects, and OAuth credentials. You can access this VeriplaceState object directly using the JSP variable identified by the id parameter. In most cases, the OAuth credentials and other configuration data are loaded from a Properties object (see Option 2 in the Using the Java SDK: Configure the Client tutorial), which can be accessed using the JSP variable identified by the properties parameter. The viewparams parameter specifies a scope used for resolving alternative views for this page, which is discussed in more detail below.

   The require-user tag enforces that a Veriplace user is discovered before the page is rendered.

   The require-location tag enforces that Veriplace location is available for the discovered user.

   The longitude, latitude, uncertainty, and address-line tags retrieve properties of the current user's location.

2. Step 2: Configuring web.xml

   The Veriplace tags require a few customizations of your application's web.xml file:

   The veriplace.properties-file context-param provides the location of the Veriplace properties file (see Option 2 in the Using the Java SDK: Configure the Client tutorial).

   The veriplace.views.tutorial.* context-params define how alternative views are rendered (see below). In this case the string tutorial matches the viewparams parameter of the setup tag.

   The servlet and servlet-mapping declarations map page.jsp to your web application's deployment URL.

3. Step 3: Adding wait.jsp

   Calls to the Veriplace API, especially for location, can take time, so it's natural to want to add an interstitial page to show the end-user while waiting for a response. The Web Tier SDK supports this naturally using another JSP:

   The meta http-equiv tag causes the page to poll for completion of the location request. An animated graphic (included with the SDK) is shown while waiting.

   The veriplace.views.tutorial.waiting context-params in your web.xml is responsible for enabling wait.jsp.

4. Step 4: Adding error.jsp and positionfailure.jsp

   Calls to the Veriplace API can sometimes fail, for example because of misconfigured credentials, failure to obtain a user opt-in, or because location was not available. You can define a default error handling page using another JSP:

   Similarly, you can define a custom error handling page for a specific error condition, in this case a position failure exception:

   The veriplace.views.tutorial.error and veriplace.views.tutorial.error.PositionFailure context-params in your web.xml file are responsible for enabling error.jsp and positionfailure.jsp. In both cases, the JSP accesses the page's VeriplaceState to show a specific error message.

5. Step 5: Done.

   You're now ready to deploy a JSP-based web application using the Veriplace API.