In this post we will discuss how to install and set up the ESRI Java Web ADF plug-in using Eclipse Ganymede. Once, we have the plug-in installed, we will set out to use the features by creating a Web Mapping Application (WMA) and extend our WMA with a Query Task functionality. 

Setting Eclipse ArcGIS Preference

Before beginning any project, it can be useful to set up common preferences for the new project wizards. Click Window > Preferences from the main menu in Eclipse. Select ArcGIS > Server from the left panel of the dialog box. The connection information entered here will be used by the project wizards. You can specify information needed to connect to some of the more commonly used servers such as ArcGIS Server, ArcIMS, and ArcGIS Web services. Each time you are prompted to add a data source, it will be automatically pre-populated with these values. 

You can also check the box to Show New Project Wizard Advanced Options. This will provide a couple of extra steps in the wizard for further customization if needed. By default this is unchecked. 

Setting up an Eclipse Server Runtime with Tomcat

In order to test and publish web applications on your application server through Eclipse, you need to define one or more resources by installing the application server and installing the appropriate server runtime in Eclipse.  Although you can set up any supported application server which supports Eclipse server runtimes, in this example we will publish our WMA to Apache Tomcat.  Once installed, it is also important to make sure that Tomcat is set to use a 1.5.x or higher JDK.  You should check by using the Configure Tomcat shortcut from the Tomcat install to display the properties dialog below. Click the Java tab and make sure the Java Virtual Machine is set to a jvm.dll located in a 1.5.x JDK. 

More information about using Tomcat in Eclipse can be found on the Eclipse wiki.  

To set up Tomcat server runtime in Eclipse, there are a few simple steps:

• Click Windows > Preferences from the Eclipse toolbar. In the Preferences dialog box, expand the Server option and select Installed Runtimes. Click the Add button.

• Navigate to the appropriate Apache Tomcat server and click Next.
  

• Click the Browse button and locate the Tomcat installation directory on your file system. Click the Installed JREs button to add a JDK as the default JRE.  Check an appropriate JDK or click Add and browse for a JDK. Click OK to close the Preferences dialog box.

• The dialog box appears as follows. Click Finish. Your Tomcat Server runtime is ready to be used when creating new projects.
  

Install ArcGIS Server for Java Web ADF plug-in
This section contains instructions on how to install/update the plug-in from ESRI update center.

• Select Help > Software Updates > from the Eclipse toolbar (1) if you have an ArcGIS Eclipse Plug-in installed and are upgrading.  Click the Installed Software tab, find ArcGIS Core and ArcGIS Server entry, right click on each and choose Update. Eclipse will go to the pre-defined update site to get the latest plug-ins. (2) If this is your first time installing the ArcGIS Server for Java Eclipse plug-in, click the Available Software tab, and click the Add Site button on the right.

• Next, click the Local button to browse to the plug-in location on disk, make sure to browse to the Server folder level in your ArcGIS Server for Java directory.

• You should now see ArcGIS added to the available software list. Check ArcGIS Core and ArcGIS Server and click Install. Once installation is complete, click Finish and follow the prompt to restart Eclipse by clicking OK.
  

Create a new ArcGIS Web ADF project
This section contains instructions for creating a new Eclipse project based on ESRI Web Project Template.

• Create a new project by clicking File > New > Project and choose ESRI Web Project under ESRI Templates. Click Next and give your project a name.
  

• Make sure to choose a Target Runtime, for example, the Apache Tomcat server runtime we set up in previous steps.

• In the New ArcGIS Web Project Window, double click Add GIS Server node.

 

• Enter the server connection credentials and click OK.  This should be pre-populated with the credentials set in the preferences dialog. 
  

 

• Choose a service from the list and add it to the webcontext. Click Finish to complete.
• Right click the project name in the Project Explorer panel, Run As > Run on Server. Pick a server and hit Finish. To view the site in an external browser, go Window > Web Browser, choose anyone other than the Internal Web Browser.

At this point, you should have a WMA running with all the default features offered by the plug-in.  In our next section, we will add a Query Task to the WMA and test it again.   

Add a query task
This section contains instructions on how to add a query task to the web application.

• In the right hand project file list, expand your project to open the mapviewer.jsp under WebContent. Once the source opens up, scroll down to the line where it says <a:task id="searchAttributesTask" . . .> (this is typically around line 123). 
  
• Place your cursor in front of this line and right click ArcGIS > Add Task > Query Attributes ...

 

• Now configure the query task. Click the Settings tab, pick a Map Service and pick a layer. Next to Query Expression, click Add.
• In the New Expression window, pick a Field to query against and either type in the value to query or select from a list of sample values. Click OK, and OK on the Add Query Task window.
• Inspect your extended mapviewer.jsp source file.  You should see the query task added and the query link added to the task menu bar.
• Run the application again and test your query task.

You now have a WMA with an extended Query Task enabled all without writing a single line of code.  The ESRI ArcGIS Server for Java plug-in hides the complexity of many features which enables you as the developer to quickly create production quality web mapping applications. 

Contributing Author, Li Linn, ESRI Java Development Team

Last week ESRI Support Center published a knowledge base article on the deprecation plans for 9.3.1. Here is a condensed list of deprecations that might impact Java developers.

• ArcGIS 9.3.1 was the last release supporting the Microsoft Windows 2000 operating system for all ArcGIS products. We will no longer support Windows 2000 in ArcGIS 9.4.
• ArcGIS 9.3.1 was the last release supporting Sun Solaris 9 for ArcGIS Server, ArcReader and  ArcGIS Engine. Sun has announced the end of life plans for Sun Solaris 9 and given the lack of availability in 2010, ESRI will no longer support this operating system. ArcGIS 9.4 will be the last release supporting Sun Solaris (all versions) for ArcGIS Server, ArcReader and  ArcGIS Engine.
• ArcGIS 9.3.1 was the last ArcGIS Server Enterprise Java release with support for the Enterprise Application Developer Framework (EADF). EADF provided out-of-the box Enterprise Java Beans (EJBs) that were ready to use and deploy across supported J2EE 1.4 application servers. Users can still take advantage of EJBs by following patterns highlighting the ArcGIS Java Web Services Toolkit (AgsJWS) and EJB3, but we will no longer provide out-of-the box EJBs as part of a Java Application Developer Framework (ADF).
• ArcGIS 9.3.1 was the last release of ArcSDE for PostgreSQL on Red Hat 4; we no longer support PostgreSQL on this operating system at ArcGIS 9.4, but we will continue to support PostgreSQL on newer versions of Red Hat Linux.
• ArcGIS 9.3.1 was the last release with support for ArcSDE for 32-bit Informix on the AIX and Solaris platforms; we will no longer support these in ArcGIS 9.4 due to limited support from IBM for these platforms.
• ArcGIS 9.3.1 was the last release of ArcSDE for Microsoft SQL Server 2000. We no longer support SQL Server 2000 in ArcGIS 9.4 due to this platform no longer being actively supported by Microsoft.
• ArcGIS 9.3.1 was the last release to support Internet Explorer 6 (IE6); we will no longer support this browser with the release after ArcGIS 9.3.1. Microsoft will be two releases ahead of IE6 by the time ArcGIS 9.4 is available, and IE6 is no longer being actively maintained by Microsoft.

Please refer the Knowledge Base Article for more information on the deprecation plans and please plan ahead for migration.

The ArcGIS Java WebServices (AgsJWS) libraries are included with the ArcGIS Java Web ADF.  With version 9.3.1, the Web ADF libraries are located under '$ARCGISHOME/java/web/webcontrols/WEB-INF/lib'.  The ESRI AgsJWS libaries include the following:

• arcgis_agsws_stubs.jar
• arcgis_ws_runtime.jar

The dependency libraries are in the same location on disk and included the following:

• activation.jar
• commons-codec-1.3.jar
• commons-httpclient-3.0.1.jar
• commons-logging-1.0.4.jar
• jaxb-api.jar
• jaxb-impl.jar
• jsr173_1.0_api.jar
  

You can create User Libraries in NetBeans and Eclipse to accelerate development with the AgsJWS API. 

NetBeans v6.5.1

1. From the tools menu, select Libraries to open the Library Manager. 
2. Click the 'New Library...' button to create a new Library and name it 'AgsJWSv9.3.1'.
3. Select a Library Type
4. You should see your library added to the Library Type you selected in the previous step.
   
5. With your new 'AgsJWSv9.3.1' library selected in the left hand Libraries pane, click the 'Add JAR/Folder' button.
6. Navigate to the '$ARCGISHOME/java/web/webcontrols/WEB-INF/lib' folder location.
7. Select the ESRI AgsJWS libraries and dependency libraries described above and click 'Add JAR/Folder'.
8. Once you have all the libraries selected, click OK to close out of the dialog.  

Now when you can add the library to an existing project by right clicking the project and selecting 'Properties'.  The Project Properties dialog opens where you can select Libraries from the list of Categories and click the 'Add Library' button to find the appropriate library to add. 

Eclipse Ganymede (v3.4.x)

1. From the Windows menu, select Preferences.
   
2. Select Java > Build Path > User Libraries from the left hand pane.
3. Click the 'New' button to create a new Library and name it 'AgsJWSv9.3.1'.
4. With your new library selected, click the 'Add Jars' button to open the Jar Selection dialog.
   
5. Navigate to the '$ARCGISHOME/java/web/webcontrols/WEB-INF/lib' folder location.
6. Select the ESRI AgsJWS libraries and dependency libraries described above and click 'Open'.
7. You should now see all the libraries added with options to attach source and javadoc locations. 

Now you can add the library to a new project or existing project by clicking the 'Add Library' in the New Project dialog and/or the Project Preferences dialog respectively.  In Eclipse, your library is added to the 'User Library' category by default.  Once you select User Library, you can add the appropriate library to your project. 

For further reference please review the follow Help System topics:

• Java WebADF Runtime Files and Components 
• Web services, SOAP, and WSDL
  

I like Swing a lot. Am I a rationally-thinking programmer? Ha! No. But I like Swing for a number of my own reasons. Let me share:

1. Swing is guaranteed to run on any JVM. No special installations or special JVMs.

2. Swing is rich with so many components and events, richer than AWT. Uh, do I understand ALL of the models and events and patterns here? No.

3. The tooling for Swing is terrific. Eclipse and Netbeans both have great tools for Swing development. I like tools. I need tools.

4. Swing is "top-to-bottom" and "bottom-to-top": I don't need to create a JPanel or JFrame before creating a JButton, or visa versa.

I do understand that there are drawbacks to using Swing as well. For starters:

1. Swing applications with heavy UIs may run a bit slow on certain platforms.

2. Swing look and feel may not always be consistent across all platforms

3. more....

SWT (The Standard Widget Toolkit) is a different beast when it comes to building UI-rich cross platform applications for the desktop. It is also a strong platform for doing what Swing and AWT do as windowing toolkits, but tries to fill the voids that Swing and AWT leave us with.

1. Swing and AWT do not render "native" widget components. SWT does use native widgets for a natural "look and feel"

2. Because Swing/AWT to not use the native widgets found on different platforms, the abstraction can cost you in performance. SWT is more native, and can perform better, as it provides the thinest possible widget support, natively, for the widest range of platforms. But care must be take when developing for specific platforms.

There are many compelling reasons for organizations to choose the RCP/SWT/Eclipse platform for their application development and maintenence environments.

OK. We have some development choices and options out there for rich Java Desktop applications. Excellent. But here is some harsh reality: SWT and AWT do not mix. Can SWT and AWT widgets co-exist in the same application? Not very well, but it can be accomplished with a little help from the SWT-AWT bridge and some complex development approaches. Here is an interesting article that goes into depth on this topic, outlining the pitfals and angst that can be experienced in trying this.

So, what does this mean for ArcGIS Engine Java developers? The high-level UI developer components that ship with the Java SDK for ArcGIS Engine are based on AWT. Period. These components have never been successfully tested in SWT or "mixed" application development environments.

What I strongly encourage Java Engine developers to do is this: avoid trying to mix SWT with ArcGIS Engine application development at all costs. At the current release, this usage will not be supported. ESRI will look into this for possible consideration later on, but at the present time, please don't go there!

So, have fun on the Swing-set, and don't hurt yourself!

Let's build our first AgsJWS web application.  The AgsJWS API is a low level API for working with ArcGIS Server Web Services through published WSDL endpoint URL's.  This makes the API easy to integrate into existing frameworks which simplifies web application development.  POJO data models make good sense when working with low level API's and Apache Wicket provides a good POJO framework which makes developing web applications simple and enjoyable.  While this post will assume some knowledge of the Apache Wicket framework, if you are new to the framework you can read more about it here. 

Our application is going to extend on our previous post which described a console based application for displaying all services from an ArcGIS Server Service Directory.  In this post, we will turn that application into a web application using the Apache Wicket framework.  

In our example, we will put all the of the files in the same package directory.  This means that our markup files and java files will be in the same directory next to one another.  

CatalogServerApplication.java

Each Wicket application is defined by an Application object.  The object defines the home page and allows for some configuration. 

package com.esri.agsjws.demo;

import org.apache.wicket.protocol.http.WebApplication;

public class CatalogServerApplication extends WebApplication {

    @Override
    public Class getHomePage() {
        // TODO Auto-generated method stub
        return CatalogServer.class;
    }

}

CatalogServer.java

In our Application object, CatalogServerApplication, we defined the CatalogServer to be our home page.  When the base URL of our application is requested, the markup rendered by the CatalogServer page will be returned. 

package com.esri.agsjws.demo;

import org.apache.wicket.AttributeModifier;
import org.apache.wicket.markup.html.WebMarkupContainer;
import org.apache.wicket.markup.html.WebPage;
import org.apache.wicket.markup.html.basic.Label;
import org.apache.wicket.markup.repeater.RepeatingView;
import org.apache.wicket.model.AbstractReadOnlyModel;

import com.esri.arcgisws.ServiceCatalogBindingStub;
import com.esri.arcgisws.ServiceDescription;

public class CatalogServer extends WebPage {

    // Constructor
    public CatalogServer(){
        // Get Version Info
        ServiceCatalogBindingStub catalog = getCatalog( endpointURL );
        String version = catalog.getMessageVersion().toString();
        add(new Label("version", version));
        add(new Label("server", endpointURL));
        
        RepeatingView repeating = new RepeatingView( "repeating" );
        add(repeating);
        
        // Get Service Info
        ServiceDescription[] sds = getServiceDesription( catalog );
        
        
        for (int i = 0; i < sds.length; i++) {
            
            WebMarkupContainer item = new WebMarkupContainer(repeating.newChildId());
            repeating.add(item);    
            
            ServiceDescription sd = sds[i];
            item.add(new Label("ServiceName", sd.getName()));
            item.add(new Label("ServiceCapabilities", sd.getCapabilities()));
            item.add(new Label("ServiceType", sd.getType()));
            
            final int idx = i;
            item.add(new AttributeModifier("class", true, new AbstractReadOnlyModel()
            {
                public Object getObject()
                {
                    return (idx % 2 == 1) ? "even" : "odd";
                }
            }));            
            
        }    
    }
    
    public static ServiceCatalogBindingStub getCatalog( String URL ){
        return new ServiceCatalogBindingStub( URL );
    }
    
    public static ServiceDescription[] getServiceDesription( ServiceCatalogBindingStub catalog ){
        return catalog.getServiceDescriptions();
    }
    
    private static String endpointURL = "http://server.arcgisonline.com/arcgis/services";
    
}

Here we integrate the console based CatalogServer class but instead of printing out to the console we are going to return our output to Wicket components to be rendered by a markup page.  First we print version and server url to Labels which take two parameters.  The first parameter is the component identifier and the second parameter is the message which the label should render.  

Next we need to iterate through our ServiceDescription and print them out in tabular form.  For this we use a WebMarkupContainer which allows us to dynamically add rows filled with Labels which we will populate with our Service Name, Capabilities, and Service Types.  I added a modifier to render alternating row colors for viewer clarity.  

CatalogServer.html

The HTML that defines our CatalogServer functionality has two obvious points to discuss
1. The wicket component declaration in form of <span wicket:id="server" id="endpointURL">
2. The message [endpointURL]

The component declaration is the Wicket identifier and the component identifier message.  The component identifier is the same as the name of the component defined as our WebPage, the CatalogServer class.  The text in between the <span> tags gets removed when the component renders its message.  The content which is rendered is determined by the CatalogServer class.

web.xml

In order to deploy our web application we need to make it known to the application server through the standard web.xml file.  

    <filter>
        <filter-name>CatalogServerApplication</filter-name>
        <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
        <init-param>
          <param-name>applicationClassName</param-name>
          <param-value>com.esri.agsjws.demo.CatalogServerApplication</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>CatalogServerApplication</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>   

We map our Application object, CatalogServerApplication, to the Wicket Filter which handles all requests.  We then provide the applicationClassName parameter linked to the fully qualified path to our CatalogServerApplication class to let Wicket know which application is available.  Also take note of the url-mapping to /*.  The Wicket filter will only process requests that are Wicket requests, everything else is ignored.  This ensures that static content will be served appropriately by the container.  

Deploy

We can now create a WAR file for deployment to our Java Application Server.  There is no further configuration necessary.  Once deployed, point your browser to the url:  http://<servername>/<warfilename> where <servername> & <warfilename) map appropriatly such as, http://localhost:8080/CatalogServer.

We have now seen how to take a console based application and easily convert it into a web application using the Wicket Framework.  Integrating the AgsJWS API with Web Application frameworks is an easy way to make efficient use of the API.  The web application described here is the foundation for building a web enabled service catalog to accurately show which services are available from appropriate servers.  I have posted the full web application with source code to the Code Gallery for you to download, deploy, and extend. I encourage you to give it a try for yourself.   

This year's event, sponsored by IBM, will feature 2 excellent speakers.

Susan Port, Platforms Systems Manager for the Municipal Property Assessment Corporation in Ontario, Canada, will be sharing the business problem and her vision of getting property tax assessment information disseminated to all the property owners of Ontario, Canada. Susan and her team were successfull in rolling out their IBM Portal system, which is based on ArcGIS Server for the Java Platform and the Java ADF.

Interested in Portal/Portlet developement with ESRI technology? Susan's talk will be very informative, and we are grateful to have her join us.

We will also be honored to have Doug Tidwell of IBM speak to us during this hour. Doug is a well known Cloud Computing expert and has given talks and presentations at many conferences world-wide, including the JavaOne 2009 International Java Developers Conference. He will be sharing the topic: "Using REST and WS-* in the Cloud".

The abstract for his talk is as follows:

"REST and WS-* are the two most common ways to access services in the cloud. In this session we'll start with a look at the REST and WS-* APIs for several common cloud services. Next, we'll look at the strengths and weaknesses of each approach and discuss why you would want to use one approach (or both) in different scenarios. We'll wrap up the session with a look at advanced features (security and transactions) and how REST and WS-* implement them. You'll leave with an understanding of these two major architectural styles and how they complement each other. "

To finish up the hour, attendees will have time to share questions and comments with Senior Java Developers from the Java Team.  ArcGIS Server and Engine for Java are YOUR products. The team is most anxious to hear your feedback on how they are serving your needs and where the Java road is taking the ArcGIS platform.

FREE LUNCH will be graciously provided by IBM, so come early and share the lunch hour with us!

Wednesday, July 15th, 12:00 noon in room 6E.

See you there!

Currently our documentation explains how to install our NetBeans Java Web ADF plug-ins by accessing a URL.  The Java Web ADF SDK includes a local repository for our NetBeans plug-in modules which you can choose to install.  Here is the process for installing from the local Java Web ADF SDK: 

• Click 'Tools->Plugins' from the main menu of the IDE.

• In the Plugins window, select the 'Downloaded' tab.

• From the 'Downloaded' tab, click the 'Add Plugins...' button and browse to the following directory in the Java Web ADF SDK, '<AGSHOME>\java\tools\netbeans_plugin'.  

• In the list of available plug-ins, check the 'Install' check box associated with your ArcGIS Java ADF plug-in.  This will enable the 'Install' button. 

• Click 'Install' and the NetBeans IDE installer window appears.

• Click 'Next' to confirm the ESRI ArcGIS Java ADF for NetBeans plug-in will be installed. 
• Read and accept the terms of the license agreement displayed and click 'Install'.

• After the installation completes successfully, click 'Finish' and restart the IDE.
  

On restart you should be able to opne the Plug-ins Dialog again and select the 'Installed' tab to see the list of installed plug-ins.  If everything went successfully, you should see the ESRI Java Web ADF plug-ins listed under the 'Web & Java EE' category. 

 

At this point you are ready to create your first ArcGIS Web Project. 

When I joined ESRI a couple of years ago, I was a brand new Java developer, fresh out of school - shapefiles and spatial references scared me to death. Today, I have come a long way and my GIS comfort zone has expanded in all directions and dimensions.  For all those new folks sailing in the same boat, thought will share with you some of my old bookmarks.

 

New to GIS

If you are a Java developer, new to GIS world,  the one great hurdle to cross is the great ocean of GIS lingo.  You might often have to find definitions for simple, yet critical concepts like a layer, mxd, geodatabase or a feature renderer. The two best locations to get started with GIS basics are the GIS Dictionary and ArcGIS Desktop Help. The GIS dictionary usually provides two line definitions of GIS terminologies whereas, the ArcGIS Desktop help has more elaborate explanation.  In fact, ArcGIS Desktop help is a user help for our ArcGIS Desktop product, but it is the best place I have found to strengthen my GIS fundamentals.  You can browse through the help to catch up on some intro and concepts on geodatabase, feature class, raster, coordinate system and geoprocessing. You may not come across those terminologies right away but it will help you in the long run.

 

New to ArcGIS Server

 If you are building JSF (Web ADF) applications,  Java Web ADF help is the best place to go. However, if you are totally new to the ArcGIS Server world, I would advise you to play with ArcGIS manager a bit and learn about publishing services, differences between SOC/SOM, GIS resource/ GIS service and how to cache maps. One stop-shop for that is our ArcGIS Server Web help!

 

New to ArcGIS Engine

If you are new to ArcGIS Engine, check out our Getting Started section on our ArcGIS Engine help. Along with that, I also strongly recommend our UC 2007 technical session video on Creating Engine Applications with Visual Java Beans. It is a lengthy one hour video, but worth every minute of it.

 

Newsletters and Video presentations

 ESRI also releases newsletters and magazines that you could subscribe to and they are also available Online. The magazines help you to get in touch with the GIS concepts. After all, it is more interesting to read a magazine than a help topic! So, here is the list :

• ArcNews is a quarterly issue that covers general news on ESRI technologies and GIS communities around the world.

• ArcWatch, magazine provides information on ESRI products and applications built on them.

• Of course, don’t forget to add ArcUser magazine to your list. The last issue of ArcUser has an interesting article: “Top Nine Reasons to use a file Geodatabase”

Also, Check out EDN site as well as Java Resource center Media Gallery for video presentations of our past conferences. The list below is my all time favorites:

• Developers Guide to the Geodatabase

• Advanced ArcGIS Engine and Java

• Building and Extending tasks for ArcGIS Server Web ADF

• Building Java Applications using the ArcGIS Server Web ADF and AJAX

At last, if you have learnt to play with Visual Java Beans or WebControls but stumped by the Automation Exceptions and Java proxies, the following list of topics will help you understand ArcObjects.

• Overview of the Java API

• Casting and Runtime type checking

• Working with variants

• Understanding the Java-COM Interop

• ArcObjects Error Codes

In all, hang in there and believe me, the more you learn it, the more you will love it, Am I not a fine example for that? Also, all those veterans out there, please feel free to comment on the blog and share your bookmarks or reminiscences of your early ArcGIS days. We all know that our new-bies definitely need some pep talk!