Using the AJAX Map Viewer Component

This tutorial shows you how to use Sun Java Studio Creator’s Integrated Development Environment (IDE) to build a JavaServer Faces web application that uses the sample AJAX Map Viewer component. You import the Java BluePrints AJAX components into the IDE, then use Google’s free map service API to create a custom map. The map includes marker text and a flag that pinpoints an address entered by the user. The sample Java BluePrints AJAX components are provided to help you learn about AJAX and to show how AJAX fits with the Java Studio Creator IDE. For an introduction to the AJAX technology, see AJAX and Sun Java Studio Creator 2.

 

Contents   - Obtaining a Google Maps API Key - Creating the AJAX Web Application - Adding a Map Coordinates Input Page - Adding a Map Marker - Adding a Map Marker Flag - Doing More With the AJAX Map Viewer Component

 

Obtaining a Google Maps API Key

 
To use the Google map service APIs, you must first create a Google account if you do not already have one, log in, and obtain a map key. The Google map key is specific to your application and allows up to 50,000 page views each day. Both the Google account and map key are free.

1. In your web browser, go to http://www.google.com/apis/maps/.

   The Google map key sign up page opens in your web browser.

2. Click Sign up for a Google Maps API key.

   The Google map key license agreement page opens in your web browser.

3. Review, then accept the agreement and enter the URL for your web site.

   To find the URL for your web site, deploy an application and look at the server name and port number. For example, http://localhost:28080/.

   The URL that you specify must exactly match the one that you use to execute the application. You may use this same key for any application using the Google Maps API that you deploy to your local application server. If you reconfigure your server to use a port or you deploy to a different server, then you must obtain another key from Google.

4. Click Generate API Key.

   Google generates your map key.

5. Copy the map key and save it in a text file or other convenient location. You use the map key as you build the AJAX map viewer application.

 

Creating the AJAX Web Application

 
Now you create the first page of the application, which contains the Map Viewer component.

1. Download and import the AJAX components if you have not already done so.
2. Create a web application project and name it AjaxMapViewer.

   AjaxMapViewer’s initial page, Page1, opens in the Visual Designer.

3. In the Palette, expand the BluePrints AJAX Components node if it is not already expanded, then drag the Map Viewer component and drop it onto Page1.

   A map image appears on Page1 and the components mapViewer1 and mapViewer1_center appear in the Outline window, similar to the following figure.

   Figure 1: Map Viewer Component

    
   

4. In the Properties window, find the Map Viewer’s key property and enter the Google map key that you saved earlier, as shown in the the following figure.

   Figure 2: Map Key Property

    
   

5. Build and run the application to see what you have so far. The AjaxMapViewer project opens in your web browser.

   Figure 3: Map Viewer Application, Take 1

    
   

Adding a Map Coordinates Input Page

 
The latitude and longitude properties of the mapViewer1_center component determine the map location. In this section, you add a page that takes a text address as input and uses the AJAX Support Bean Geocoding Service Object component to convert the address into latitude and longitude coordinates. You add latitude and longitude properties to the Request Bean and use these properties to set the coordinates on the mapViewer1_center component.

 
Designing the Map Coordinates Input Page

1. In the Projects window, right-click AjaxMapViewer > Web Pages and choose New > Page from the pop-up menu.
2. In the New Page dialog box, type the file name GetCoordinates, and click Finish.

   The IDE opens the GetCoordinates page in the Visual Designer. The following figure shows the page you will design.
    
   

   Figure 4: GetCoordinates Page Design

    

3. From the Basic section of the Palette, drag a Label component and drop it in the upper-left corner of the page. Set the text of the Label to Enter an address:
4. Drag a Text Field component and drop it to the right of the Label component. In the Properties window, set the Text Field’s required property to True.
5. Drag a Button component onto the page and drop it below the Text Field component. Set the Button’s text property to Get Map and the id property to getMap.
6. Drag a Message Group component onto the page and drop it below the Get Map button.

 
Setting Up Page Navigation

1. Right-click anywhere in the Visual Designer and choose Page Navigation from the pop-up menu.

   The Page Navigator window opens in the IDE.

2. Click the GetCoordinates.jsp icon and drag a connector from the getMap button to Page1.jsp.
3. In the Projects window, right-click the AjaxMapViewer > Web Pages > GetCoordinates node and choose Set As Start Page from the pop-up menu.

   A green arrow appears next to the GetCoordinates node, as shown in the following figure.

   Figure 5: GetCoordinates Start Page Mark

    
   

Adding the Input Logic

 

1. Return to the GetCoordinates page by clicking its tab.
2. From the BluePrints AJAX Support Beans section of the Palette, drag the Geocoding Service Object component and drop it anywhere the GetCoordinates page.

   The geoCoder1 component appears in the Outline window, as shown in the following figure.

   Figure 6: geoCoder1 in the Outline Window

    
   

3. If you are working behind a firewall, configure the proxy settings on the geoCoder1 component because it does not retrieve the proxy settings from the IDE. If you are not working behind a firewall, skip this step.
   1. In the Properties window for the geoCoder1 component, set the proxyHost property to the appropriate proxy for your location.
   2. Set the proxyPort property to the appropriate port for your location.

Adding Latitude and Longitude Properties to the Request Bean

 

1. In the Outline window, right-click RequestBean1 and choose Add > Property from the pop-up menu.

   The New Property Pattern dialog box opens.

2. Enter longitude in the Name field and double (lower-case) in the Type field, and then click OK.
3. Create a second Request Bean property. Enter latitude for the Name and double (lower-case) for the Type, and then click OK.
4. Double-click the Get Map button in the Visual Designer. The IDE opens the GetCoordinates page in the Java editor at the getMap_action() method.
5. Add the following code (shown in bold) to the getMap_action() method.

   Code Sample 1: GetMap Button Code

   public String getMap_action() { GeoPoint points[] = geoCoder1.geoCode((String)textField1.getText()); if (points.length < 1) { error("Sorry, cannot find that location; please be more specific."); return null; } getRequestBean1().setLatitude(points[0].getLatitude()); getRequestBean1().setLongitude(points[0].getLongitude()); return "case1"; }

    
   

6. Right-click in the Java Editor, then choose Fix Imports from the pop-up menu to resolve the GeoPoint not found error.
7. Click the Page1 tab and then click the Java button.
8. In the Java Editor for Page1, scroll down to the prerender() method and add the following code shown in bold.

   Code Sample 2: prerender Method

   public void prerender() { mapViewer1_center.setLatitude(getRequestBean1().getLatitude()); mapViewer1_center.setLongitude(getRequestBean1().getLongitude()); }

    
   

9. Build and run the application. AjaxMapViewer opens in your web browser. Enter a physical address, such as 15 Network Circle, Menlo Park, CA, and click the Get Map button. A map showing the location you entered opens in your web browser, similar to the following figure.
    
   

   Figure 7: Map Viewer Application: Take 2

    
   

Adding a Map Marker

 
The map you created in the previous section shows the area around the location you entered, but does not pinpoint the location itself. In this section, you add a map marker to the application.

 

1. Open the Design View for Page1.
2. From the BluePrints AJAX Support Beans section of the Palette, drag a Map Marker component and drop it anywhere on Page1.
3. In the Properties window for mapMarker1, set the markup property to This is the place!.
4. In the Outline window, right-click the mapViewer1 component and choose Property Bindings from the pop-up menu.
5. In the Property Bindings dialog box, bind mapViewer1’s info property to Page1’s mapMarker1 property, as shown in the following figure. Click Apply, then Close.

   Figure 8: Binding the mapViewer1 info Property to mapMarker1

    
   

6. Double-click anywhere on Page1 to open the Java Editor.
7. Scroll to the prerender() method and add with the following two lines shown in bold.

   Code Sample 3: prerender() Method With Map Marker Support

   public void prerender() { mapViewer1_center.setLatitude(getRequestBean1().getLatitude()); mapViewer1_center.setLongitude(getRequestBean1().getLongitude()); mapMarker1.setLatitude(mapViewer1_center.getLatitude()); mapMarker1.setLongitude(mapViewer1_center.getLongitude()); }

    
   This code sets the coordinates on the mapMarker1 component so that it points to the location on which the map is centered.

8. Build and run the application. When the AjaxMapViewer application opens in your web browser, enter an address such as 15 Network Circle, Menlo Park, CA, and then click the Get Map button. The map opens in your web browser with a map marker pointing to the location, similar to the following figure.
    
   

   Figure 9: Map Viewer Application: Take 3

    
   

Adding a Map Marker Flag

 
Finally, you add a map marker flag to further pinpoint the map location. 

1. In the Java Editor for Page1, find the public class Page1 extends AbstractPageBean declaration. Add the following code (shown in bold) under the Creator-Managed Component Definition code fold.
   

   Code Sample 4: Adding a MapMarker Array to Page1

   public class Page1 extends AbstractPageBean { Creator-managed Component Definition private MapMarker[] markers; public MapMarker[] getMarkers(){ return markers; }

    

2. Scroll to the prerender() method and add the following two lines of code shown in bold.
   

   Code Sample 5: prerender() Method With Map Marker Flag Code

   public void prerender() { mapViewer1_center.setLatitude(getRequestBean1().getLatitude()); mapViewer1_center.setLongitude(getRequestBean1().getLongitude()); mapMarker1.setLatitude(mapViewer1_center.getLatitude()); mapMarker1.setLongitude(mapViewer1_center.getLongitude()); markers = new MapMarker[1]; markers[0] = mapMarker1; }

    

3. Click the Design button to return to the Page1 Design View.
4. In the Outline window, right-click the mapViewer1 component and choose Property Bindings from the pop-up menu.
5. In the Property Bindings dialog box, bind mapViewer1’s markers property to Page1’s markers array, as shown in the following figure. Click Apply, then Close.
    
   

   Figure 10: Binding the Markers Property to the Markers Array

    
   

6. Build and run the application. Enter an address such as 15 Network Circle, Menlo Park, CA, and then click the Get Map button. The map opens in your web browser with a map marker and flag pointing to the location, similar to the following figure.
    
   

   Figure 11: Map Viewer Application: Take 4

    
   

Doing More With the Ajax Map Viewer Component

 
Try It. In the section Adding a Map Marker Flag, you added a MapMarker array to contain the map marker and marker flag. Try using the array to place multiple markers on the map.

 
Try It. This tutorial shows how to store the MapMarker array at page scope. Try storing the MapMarker array at session scope and implement an “add a marker” page to add markers to the map. Ensure that the extra addresses you provide appear on the map at the scale factor you are using. The default scale factor is 4.

 
Try It. This tutorial shows how to use one Java BluePrints AJAX map component to create one custom map. Try building an application that creates more than one map. Rather than store the Google map service API key as a property on each map component that you use, create a context initialization parameter named com.sun.j2ee.blueprints.ui.mapviewer.KEY in your web.xml file and store the Google map service API key value there.