How to create an add-in application extension

Summary
This topic guides you through the workflow for creating an application extension using the Eclipse integrated development environment (IDE). After the workflow is presented, the topic takes a closer look at the abstract Extension class and defines additional methods available to you when creating your application extension.

In this topic

About the application extension

An application extension provides an end user with additional geographic information system (GIS) functionality for specific problems. Typically, functions that perform a specific task can be grouped into and made available through an extension, and often represent a domain. Good examples of extensions in ArcMap are the 3D Analyst extension, Business Analyst extension, and so on. The 3D Analyst extension is used when you are working with three-dimensional datasets, while the Business Analyst is helpful for business organizations.
The following guides you through the process of creating an application extension using the Eclipse IDE. Before beginning this workflow, make sure that you have created an ArcMap add-in project using Eclipse. For more information, see How to create an add-in project in Eclipse. Since there is no difference between creating an application extension for any one of the ArcGIS for Desktop applications, this workflow shows you how to create an application extension for ArcMap.
The workflow for creating an application extension in Eclipse consists of the following (done in the order as shown):

Creating an application extension

The following shows you how to create an application extension for an existing Eclipse add-in project. Ensure the Add-In view is enabled on the Add-In Editor for the config.xml file and that you have completed the required Add-In Overview properties. See the following screen shot:

  1. Under All Add-Ins, click the Add button. The Create New Add-In dialog box appears.  See the following screen shot:

  1. Select the Application Extension option on the preceding screen shot (there are eight different options), then click OK.

    A new section of the add-in editor appears with a number of properties for you to set for your new application extension. By default, the id* and class* fields are completed with default values to help expedite the development process. Also, observe the warning symbol under Extension Details and next to the class* property. This indicates that the Java class for your new application extension has not been created. In a later step in this workflow, you will learn how to create your Java class and where you write your business logic. For now, the following screen shot shows you the new Extension Details section that is added to the add-in editor with default values:

Setting properties

An application extension has a number of properties for you to set. The following is a list of all of the properties with an explanation for each:
The following explains the additional properties that can be applied:

Creating a Java class and defining your business logic

At this stage, you have finished adding values for all of the properties needed to define your application extension. The final stage in this workflow is to create a Java class that contains your business logic. Do the following steps to create a Java class:
  1. Click the class* property on the Extension Details section. A new Java class dialog box appears with a few pre-populated form boxes. The one of interest is the superclass property. This property is unavailable automatically because the class that you create must inherit the abstract class named Extension from the com.esri.arcgis.addins.desktop package. This abstract class is what is used to hide the implementation details for making your application extension work with a desktop application.
  2. Add a name for your new Java class file and click finish.
A class in this instance, called ArcMapExtension, is similar to the one generated next. See the following code example:
[Java] 
public class ArcMapExtension extends Extension{
    @Override public void init(IApplication app){}
}
The generated class file has two significant pieces. The first is the use of the extends keyword to inherit from the abstract class called Extension. The second is the auto-generated method, as illustrated. The init() is required and is described in greater detail as follows:
[Java] 
private IApplication app;
@Override public void init(IApplication app){
    this.app = app;
}
Once you have a reference to the application object, you can use it to a reference to the desktop application the application extension is being used in with the following code example:
  1. Obtain an object reference to ArcMap:
[Java] 
IMxDocument mxDocument = (IMxDocument)app.getDocument();
  1. Obtain an object reference to ArcCatalog. See the following code example:
[Java] 
IGxDocument gxDocument = (IGxDocument)app.getDocument();
  1. Obtain an object reference to ArcGlobe. See the following code example:
[Java] 
IGMxDocument gMxDocument = (IGMxDocument)app.getDocument();
  1. Obtain an object reference to ArcScene. See the following code example:
[Java] 
ISxDocument sxDocument = (ISxDocument)app.getDocument();
A second purpose for this init() method is to define what the application extension houses. For example, this could be a toolbar, a dockable window, and so on. The following takes a closer look at how you might have a dockable window opened when a user opens a new map document. In How to create an add-in dockable window, the workflow for creating a dockable window is examined in detail and that same add-in will be utilized here for the application extension. The following code example shows you how to achieve this piece of functionality:
[Java] 
private MxDocument mxDoc;
private IDockableWindow dockableWindow;

@Override public void init(IApplication app){
    //Get the dockable window manager.
    IDockableWindowManager dwm = new IDockableWindowManagerProxy(app);

    //Get the unique ID representing the add-in dockable window already created.
    UID uid = new UID();
    uid.setValue("com.esri.arcgis.arcmap.addin.arcmapdockablewindow");

    //Use the uid object to get an object pointing to the docable window.
    dockableWindow = dwm.getDockableWindow(uid);

    //Get an object pointing to the map document.
    mxDoc = (IMxDocument)app.getDocument();

    //Set up an event to respond to a new document event in ArcMap.
    ((MxDocument)mxDoc).addIDocumentEventsListener(new IDocumentEventsAdapter(){
        @Override public void newDocument(IDocumentEventsNewDocumentEvent e){
            if (dockableWindow != null){

                //Display the dockable window.
                dockableWindow.show(true); 
            }
        }
    }
        ;
}
The first four lines of code in the init() method are described in detail in the topic for creating a dockable window. To summarize, obtain an object to a dockable window that has already been created and defined. Next, proceed to use the application object passed into the init() method to obtain a reference to the ArcMap application, stored in the mxDoc variable. Next, the IDocumentEventsListener is added to the application, so you can write code to display your dockable window every time a new map document is opened within ArcMap. There are two items worth mentioning with the code that achieves this. First, is the use of the IDocumentEventsAdapter class, which allows you to override the desired methods in the anonymous inner class. The second point of interest is the method that is overridden is the newDocument() method of the IDocumentEvents interface. Every time a new map document is opened within ArcMap, this method will be called from the framework and executed. Within the method, the dockable window is enabled by calling the show() method on the dockable window object.
When the previous example is deployed (for more information, see How to deploy your add-in), and ArcMap is opened, the dockable window shows. If the "Click Me!" button within the dockable window is clicked, then a message dialog box appears showing the "Hello, World!" message. If the dockable window is close, the only way it can be retrieved is by opening a new map document. 
In the previously mentioned, How to create an add-in dockable window, the workflow looked at tying a dockable window to a button, while in this scenario, it is tied to an application extension, which has been designed to open the dockable window only when a new map document is opened.

About the abstract class Extension

The abstract class Extension provides you with an additional method that can be overridden to add additional capabilities to your application extension.  This additional method is described in detail as follows.

shutdown() method

This method is called by the ArcGIS framework when a user closes one of the ArcGIS for Desktop applications in which your application extension resides. You can override this method to release any resource that is no longer necessary when the application is closed.

Persisting objects

It is feasible that you might want or need to store information that is used by your application extension to maintain state between various sessions of a desktop application. To do this, you can utilize Java's externalizable interface. This interface has the following methods that you must provide implementation details for:
To take advantage of this, define your class to implement the externalizable interface and provide your business logic for the two methods. The following code example gives you a skeleton for how the application extension looks like:
[Java] 
public class ArcMapExtension extends Extension implements Externalizable{
    @Override public void readExternal(ObjectInput in){}
    @Override public void writeExternal(ObjectOutput out){}
}
After you have finished adding your business logic to the preceding two methods you are finished. The ArcGIS add-in framework will invoke these methods at the appropriate time when the application extension is being used.

Understanding the config.xml file

When setting all of the properties, the config.xml file was being generated behind the scenes for you. To understand more about how this config.xml file is created, see Understanding the config.xml.

Creating different types of customizations

This topic showed how to create an application extension. However, there are additional types of add-ins that can be created and defined. See the following topics that discuss each type of add-in.





Development licensingDeployment licensing
ArcGIS for Desktop BasicArcGIS for Desktop Basic
ArcGIS for Desktop StandardArcGIS for Desktop Standard
ArcGIS for Desktop AdvancedArcGIS for Desktop Advanced