Developer: Business Intelligence

Building Open-Standard Portlets for Location Information
by Justin Lokitz

Learn how to integrate geographic maps into open-standard portlets.

Downloads for this article
 Sample code
 Oracle JDeveloper 10g
 Oracle Portal Add-in for JDeveloper
 Oracle Application Server MapViewer
 Oracle MapViewer Extensions for JDeveloper
 OC4J 10g
 Oracle Java Portlet Container

In business, information is king. With the advent of enterprise portals, getting pertinent information has become as easy as logging onto a single Web site and using a single password. The enterprise portal has moved beyond the custom-built executive dashboard to become an indispensable backdrop through which all end users (employees, citizens, and customers alike) can glean the information they need at a moment's notice without needing to install special software (other than a standard browser), use a particular operating system and/or device, or open more than one window.

The same can be said for location information. In a previous article (" Using Location Information in Enterprise Reporting "), I stated that "location information is everywhere; it can be found across all lines of business, all industries, and in virtually every organization and department in the world." With the release of that article and the push for location-based intelligence in such venues as the 2005 Location Technology & Business Intelligence Conference, it has never been more evident that finding patterns in location data, as it exists in tandem with relational data, is increasingly important, if not imperative. Today, executives, analysts, and citizens all need to see information as it pertains to location attributes, and they want this information at their fingertips.

Today, we have the ability to meet these needs. As enterprise portals become the norm throughout all organizations and lines of business, it has become essential to find new ways to integrate disparate information and applications into all portal frameworks. In a sense, this is the exact definition of a portal: "a place to aggregate content, applications, and services" (Laura Ramos, Forrester Research, "Portal Definition Update: Evolving to the Collaborative Business Platform," December 18, 2002) without redefining or redeveloping the content, applications, and/or services.

Hence, in the interest of being able to share content, applications, and services to be aggregated into a portal, the enterprise portal vendor community has helped ratify two new portal standards that revolve around sharing this content via portlets: OASIS Web Services for Remote Portlets (WSRP) and Java Specification Request 168 (JSR 168). Because these new standards make it easy to share all information and applications as portlets, it has become easy to build location into the equation—as in building location portlets (maps) alongside business intelligence portlets.

In this article, I'll discuss how to develop portlets, using open standards such as WSRP and JSR 168, that incorporate location information and applications such as geographical maps. All of the portlet code this article describes can be registered in any vendor's portal solution that supports the portlet standards WSRP and JSR 168.

Defining the Map

The following examples use Oracle Application Server MapViewer (Oracle MapViewer) and Oracle JDeveloper 10g to define and develop dynamic, Web-based maps. Although in theory, any Web-based mapping technology could be used to produce the same outcome, Oracle MapViewer makes it easy, because it provides Java and XML APIs as well as a JavaServer Page Tag Library, so that anyone, from a beginning developer to a more advanced developer, will find it straightforward (and quite powerful) to integrate maps into existing and new development projects. For more information, including download and setup instructions, see .

In my last article, " Use Location Information in Enterprise Reporting ", I explained how you define maps for Oracle MapViewer by using the map definition tool and/or Oracle SQL*Plus. For continuity and simplicity, this article uses the same example, which includes sample data found in the OE schema, originally set up with Oracle by Example: " Performing Location-Based Analysis ".

Like other map-rendering tools, Oracle MapViewer uses the concepts of styles (colors, markers, lines, areas, text, symbology, and advanced styles) and themes (sometimes called layers) to create dynamic maps. The definitions of these attributes, as well as actual map definitions, are stored as XML in the database, along with the location information.

To create attributes and/or map definitions, you can issue standard SQL inserts/updates to the database, such as the following:

SQL> insert into USER_SDO_STYLES values(
      'V.PIECHART1', 'ADVANCED', null, 
      '<?xml version="1.0" ?>
              <PieChartStyle pieradius="10">
                      <PieSlice name="A"    color="#ffff00" />
                      <PieSlice name="B"    color="#000000" />
                      <PieSlice name="H"    color="#ff00ff" />
                      <PieSlice name="I"    color="#0000ff" />
                      <PieSlice name="W"    color="#ffffff" />
      </AdvancedStyle>',  null, null);

Or you can use the supplied Map Definition Tool (see Figure 1), which does most of the work for you.

figure 1
Figure 1: Map Definition Tool

The standard Oracle MapViewer download or deployment included with Oracle Internet Application Server has a set of styles, themes, base maps, and sample code. However, for our example, you will need to copy one base map and add two themes. Because you have both SQL and tool access to the map definitions in the database, the easiest way to copy the definition of a map is to issue a SQL statement like the following. (Before doing this, examine the Oracle MapViewer-related views user_sdo_styles, user_sdo_themes, and user_sdo_maps for a better understanding of how they work.)

SQL> insert into user_sdo_maps
  2  values('WAREHOUSES_AND_CUSTOMERS', 'customers and warehouses',
  3  (select definition from user_sdo_maps where name='DENSITY_MAP'));

1 row created.

SQL> commit;

Commit complete.

You now have a new base map named WAREHOUSES_AND_CUSTOMERS, to which you will add some themes by using the Map Definition Tool. First, change to the directory containing mapdef.jar and issue the following command to connect to the Oracle Database instance that is storing our map definitions:

java -classpath mapdef.jar;d:\oracle\ora92\jdbc\lib\classes12.jar
-Dhost="localhost"  -Dsid="orcl" -Dport="1521"

Next, create two themes, CUSTOMERS and WAREHOUSES (see Figures 2 and 3).

figure 2
Figure 2: Creating the CUSTOMERS theme

figure 3
Figure 3: Creating the WAREHOUSES theme

After creating the customers and warehouses themes, add them to our new WAREHOUSES_AND_CUSTOMERS base map (see Figure 4).

figure 4
Figure 4: Creating the WAREHOUSES_AND_CUSTOMERS map definition

Note the Min Scale and Max Scale elements, which are for defining which themes appear on a given map, depending on the zoom level of a request. After updating the map definition (by clicking on the Update button), you can begin to use them to build dynamic maps based on client requests. An easy way to test that our map is working is to plug this new map definition name, WAREHOUSES_AND_CUSTOMERS, into one of our demo Oracle MapViewer applications. To do that, navigate to our Oracle MapViewer simple map client (mapclient.jsp at the Oracle MapViewer URL) and enter the necessary values (see Figure 5).

figure 5
Figure 5: Demo map client

Note that the mapclient.jsp sample application also displays the issuing request made to the Oracle MapViewer server—this is the same XML request that can be made by any client or development language. If all definition and connection values are correct, a map (or a URL to the map image) will be built upon request.

Building the Portlet Framework

Developing portlets using the newest standards such as JSR 168 and WSRP can be relatively painless if you use the right tool. Luckily, the Oracle Internet Application Server Portal team has developed such a tool for Oracle JDeveloper 10g, the "portal-addin." The portal-addin is an extension to Oracle JDeveloper 10g that makes it possible to quickly and effortlessly produce a Java (JSR 168) portlet framework by using wizards. Once you have developed portlets by using the JSR 168 specification, you can deploy them to any application server that supports this standard, including Oracle Internet Application Server, and call them via WSRP. For information about the portal-addin or portlet standards, see: .

To develop our portlet framework by using JDeveloper 10g, you first create a new workspace called WSRPMapPortlet; for this workspace, you use the default Web application template (see Figure 6).

figure 6
Figure 6: Creating a new application workspace

By right-clicking on the ViewController project within the newly created workspace, you can choose "new" to start one of the many extensions. Although you may not see the portlet wizards within the Web Tier section," the portlet wizards will appear if you choose to filter by "all technologies" rather than "project technologies. From here, you choose the Java Portlet Wizard, which will lead you through the process of creating a Java standard portlet (see Figure 7).

figure 7
Figure 7: Java portlet creation

Although there are many definable options in the Java Portlet Wizard, you will choose mostly defaults for this example (see Figures 8 through 11). For full documentation on the other Java Portlet Wizard options, see the Oracle Internet Application Server Portal Developer's Guide .

figure 8
Figure 8: Specifying the portlet class

figure 9
Figure 9: Specifying the portlet name

figure 10
Figure 10: Exploring the portlet modes

figure 11
Figure 11: Portlet view.jsp page

Now that our open portlet framework is complete, you can add our Oracle MapViewer code to it.

Integrating Oracle MapViewer with an Open Standard Portlet

As in previous Oracle MapViewer examples, for simplicity, you will use the MapViewer JSP Tag Library to call our MapViewer instance and return dynamic, Web-based maps to our portlet. In general, working with the MapViewer JSP Tag Library is not only easy but also well documented and makes for a flexible solution. For a how-to, see .

Now, to add code to our recently created portlet framework, you open the view.jsp file, by double-clicking on it in JDeveloper. Within the JDeveloper design mode, you can now add any formatting or content you want, without having to dive into complex HTML—for this project, center the content, using the center icon. While you are in design view, you can also drag, drop, and define our tags. To use the Oracle MapViewer tags, select MapViewer Tag Library from the Component Palette (usually at the top right of JDeveloper 10g). From the MapViewer Tag Library, drag the init tag to the page just below the defineObjects tag added by the Portlet Wizard. As you can see, the init tag has three fields, two of which must be completed—you complete all three with the following information: URL (, datasource (mvdemo), and user-defined ID (mvHandle)—see Figure 12.

figure 12
Figure 12: Adding the init tag and applicable specifications

The next step is to add the setParam tag to the page. Note that although the setParam tag does not pop up an info window, if you select the tag on the page, you can set the Oracle MapViewer parameters in the Property Inspector (usually at the bottom right of JDeveloper 10g). While the setParam tag is selected, fill in the following parameters: antialiasing (true), basemap (WAREHOUSES_AND_CUSTOMERS), centerX (-122.4), centerY (37.8), height (450), size (10), title (My Map Portlet), and width (600)—see Figure 13.

figure 13
Figure 13: Adding the setParam tag and applicable specifications

Once you have finished filling out the parameters for the setParam tag, drag the run tag, which does not need any parameters, to the page (see Figure 14).

figure 14
Figure 14: Adding the run tag

Finally, you are ready to render our map within the context of the portlet. In the previous calls to our Oracle MapViewer instance, using the tag library, you basically set up the entire map environment, and the Oracle MapViewer instance has subsequently already built the map image upon receiving the Run command. Now all you have to do is place that image on the page. To do this, you must first drag a standard HTML image tag to the page (or an object tag if the image is an SVG). From the Component Palette, select HTML, drag the image tag to the page, and click on the source tab to see the JSP/HTML source for our page. Once again in the Component Palette, select MapViewer Tag Library, and this time drag the getMapURL tag between the empty quotation marks of the image tag (the image tag should now look like this: <img src="<mapviewer:getMapURL />"/>). Once the page runs and Oracle MapViewer creates this image, the getMapURL tag will provide an actual image URL back to the HTML image tag (Figure 15).

figure 15
Figure 15: Adding the HTML image tag and the Oracle MapViewer getMapURL tag

At this point, you have enough code to be able to deploy our portlet in such a way that any portal can digest it and will thus see our map. This also gives you a good starting point for adding quite a bit more logic, thereby being able to add different versions of the map for different requests. However, this is as far as this example goes.

Deploying and Registering the Location-Enabled Portlet

You are now at a point where you can deploy our portlet to a WSRP/JSR 168-compliant portlet container such as Oracle Container for J2EE (OC4J). To do this, right-click on the web.xml file in the ViewController project, in the Web Content>WEB-INF folder, and choose "Create WAR deployment profile." As a deployment profile name, choose WSRPMapPortlet and also specify our J2EE Web context root with the same name (WSRPMapPortlet)—see Figure 16.

figure 16
Figure 16: Creating a deployment profile

Once you've built the deployment profile, you can right-click on it and choose to deploy the project as a WAR or EAR file or to an application server of your choice. In our case, choose to deploy the project directly to the OC4J instance where our portlet_container exists (Figure 17).

figure 17
Figure 17: Deploying the portlet to the portlet container

Upon successful deployment, you can view the WSRP-WSDL page by navigating to This address is the same as the one you also use to register our new portlet with the portal (Figure 18).

figure 18
Figure 18: Portlet WSRP specification

The easiest way to test the newly created WSRPMapPortlet is to use the Oracle Portal/WSRP Verification Server, which is a hosted prerelease version of Oracle Application Server Portal capable of communicating with WSRP producers/portlets. As long as our portlet can be called outside of our corporate firewall, verifying its ability to render what you just created is relatively easy via this service (Figure 19).

figure 19
Figure 19: Testing the WSRP map portlet

For information on the verification process, see this documentation.


As integration technologies such as portals and intelligence data become critical pieces of the business infrastructure, being able to share the information we use and the applications (portlets) we build becomes utterly essential (if not legally required). Today, we not only have all the ingredients we need for creating new applications that adhere to open standards but we also have framework standards, such as JSR 168 and WSRP, that make it possible to integrate existing technologies and data into new applications. The point of convergence of these new technologies with existing technologies, such as GIS and portals, is where we will finally be able to gain real-world intelligence from all of the data without having to wade through a mire of complexity to do so.

Justin Lokitz is a Senior Sales Consultant at Oracle Corporation specializing in GIS and J2EE development.

Please rate this document:

Excellent Good Average Below Average Poor

Send us your comments