com.esri.arcgis.system
Class ExtensionManager

java.lang.Object
  com.esri.arcgis.system.ExtensionManager

All Implemented Interfaces:

IExtensionManager, IExtensionManagerAdmin, IJITExtensionManager, ISupportErrorInfo, java.io.Serializable

public class ExtensionManager

extends java.lang.Object

implements IExtensionManager, IExtensionManagerAdmin, ISupportErrorInfo, IJITExtensionManager

Extension Manager - a singleton.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Description

The ExtensionManager is designed to allow you to enable licensed extensions, such as ArcGIS 3D Analyst, within your standalone application.

Being a singleton object, ExtensionManager is the one and only instance of its class. An application can have only one ExtensionManager object. You could cocreate and use ExtensionManager from within ArcMap, but there is no real need as the IExtensionManager interface is also available on the Application object.

See the About Extensions topics for more details.

Remarks

If you are building an application that makes use of licensed extension functionality like ArcGIS Spatial Analyst, ArcGIS 3D Analyst, or ArcPress for ArcGIS, you need to take responsibility for enabling the extension you're using.

The ExtensionManager was designed for this purpose. The model is that you create the ExtensionManager and hold onto it for the life of your application. Before you use a licensed extension, you need to load it and enable it. You load the extension using IExtensionManagerAdmin::AddExtension and passing in the CLSID of the extension. Then before you use the extension, you need to enable it.

To enable the extension, find the extension using IExtensionManager::FindExtension , QI for IExtensionConfig on the extension, and then set the State property to esriESEnabled. Keep in mind that setting this property may fail, so be prepared to handle that in your application. If enabling the extension succeeds, that means that the license was checked out. If not, then the license could not be acquired.

If during the life of your application, you want to give the license back, simply set the state to esriESDisabled. If that succeeds the license was checked back in. If it failed that means there are outstanding objects (from the extension) that are still using the license.

See Also:

IExtensionManager, IExtensionManagerAdmin, IExtension, IExtensionConfig, Serialized Form

Constructor Summary

ExtensionManager()
Constructs a ExtensionManager using ArcGIS Engine.

ExtensionManager(java.lang.Object obj)
Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.

Method Summary

void	addExtension(IUID extensionCLSID, java.lang.Object initializationData) Creates a single extension given the CLSID, then passes initializationData to IExtension::Startup.
boolean	equals(java.lang.Object o) Compare this object with another
IExtension	findExtension(java.lang.Object nameOrID) Finds the extension by CLSID (IUID) or name (String).
IExtensionManager	getAsIExtensionManager() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
IExtensionManagerAdmin	getAsIExtensionManagerAdmin() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
IJITExtensionManager	getAsIJITExtensionManager() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
ISupportErrorInfo	getAsISupportErrorInfo() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
static java.lang.String	getClsid()
IExtension	getExtension(int index) The extension at the specified index.
IUID	getExtensionCLSID(int index) The CLSID of the extension at the specified index.
int	getExtensionCount() The number of extensions loaded in the application.
IUID	getJITExtensionCLSID(int index) Retrieves the CLSID of the JIT Extension at index.
int	getJITExtensionCount() The number of just in time extensions registered with the application.
int	hashCode() the hashcode for this object
void	insertExtension(IUID pExtCLSID, IExtension pExtension) Adds an extension to the manager without initialization.
void	interfaceSupportsErrorInfo(GUID riid) Supported Platforms
boolean	isExtensionEnabled(IUID pExtCLSID) Returns whether the extension is currently checked on.
boolean	isLoaded(IUID pID) Returns whether the extension is currently loaded.
void	removeExtension(IExtension pExtension) Removes a just in time extension from the manager.
void	shutdownExtensions() Shuts down and releases the extensions that are loaded and calls IExtension::Shutdown.
void	startupExtensions(IUID componentCategory, IUID jitCategory, java.lang.Object initializationData) Creates and starts the extensions for the given component category, passing initializationData to each in IExtension::Startup.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ExtensionManager

public ExtensionManager()
                 throws java.io.IOException,
                        java.net.UnknownHostException

Constructs a ExtensionManager using ArcGIS Engine.

Throws:

java.io.IOException - if there are interop problems

java.net.UnknownHostException - if there are interop problems

ExtensionManager

public ExtensionManager(java.lang.Object obj)
                 throws java.io.IOException

Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.

Construct a ExtensionManager using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to ExtensionManager.
ExtensionManager theExtensionManager = (ExtensionManager) obj;

Parameters:

obj - an object returned from ArcGIS Engine or Server

Throws:

java.io.IOException - if there are interop problems

Method Detail

getClsid

public static java.lang.String getClsid()

getAsIExtensionManager

public IExtensionManager getAsIExtensionManager()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

getAsIExtensionManagerAdmin

public IExtensionManagerAdmin getAsIExtensionManagerAdmin()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

getAsISupportErrorInfo

public ISupportErrorInfo getAsISupportErrorInfo()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

getAsIJITExtensionManager

public IJITExtensionManager getAsIJITExtensionManager()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

equals

public boolean equals(java.lang.Object o)

Compare this object with another

hashCode

public int hashCode()

the hashcode for this object

getExtensionCount

public int getExtensionCount()
                      throws java.io.IOException,
                             AutomationException

Description copied from interface: IExtensionManager

The number of extensions loaded in the application.

Supported Platforms

Windows, Solaris, Linux

Description

Returns the number of extensions currently loaded in the application.

Specified by:

getExtensionCount in interface IExtensionManager

Returns:

The count

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getExtension

public IExtension getExtension(int index)
                        throws java.io.IOException,
                               AutomationException

Description copied from interface: IExtensionManager

The extension at the specified index.

Supported Platforms

Windows, Solaris, Linux

Description

Returns the extension at the specified index from the extensions currently loaded in the application. The first extension has an index of 0 and the last extension has in index of ExtensionCount - 1.

Remarks

This is not the only way to get a reference to an extension; the IApplication interface has FindExtensionByCLSID and FindExtensionByName methods.

Specified by:

getExtension in interface IExtensionManager

Parameters:

index - The index (in)

Returns:

A reference to a com.esri.arcgis.system.IExtension

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getExtensionCLSID

public IUID getExtensionCLSID(int index)
                       throws java.io.IOException,
                              AutomationException

Description copied from interface: IExtensionManager

The CLSID of the extension at the specified index.

Supported Platforms

Windows, Solaris, Linux

Description

Returns the unique identifer (UID) of the extension at the specified index from the extensions currently loaded in the application. The first extension has an index of 0 and the last extension has in index of ExtensionCount - 1.

Specified by:

getExtensionCLSID in interface IExtensionManager

Parameters:

index - The index (in)

Returns:

A reference to a com.esri.arcgis.system.IUID

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

findExtension

public IExtension findExtension(java.lang.Object nameOrID)
                         throws java.io.IOException,
                                AutomationException

Description copied from interface: IExtensionManager

Finds the extension by CLSID (IUID) or name (String).

Supported Platforms

Windows, Solaris, Linux

Description

The FindExtension method will get an extension by either its name string or by its CLSID. Using IExtensionManager is not the only way to get a reference to an extension; the IApplication interface has FindExtensionByCLSID and FindExtensionByName methods.

nameOrID is a variant representing the identifier of the extension. This can either be the UID of the extension or the name string.

Remarks

COM coclasses are identified by a globally unique identifier (GUID). There two formats for the GUID for a coclass: a class ID (CLSID) and a ProgID. The ProgID is a text alias for a CLSID. The UID coclass can be used to represent the GUID of an extension object. You can set the IUID.Value property to either the CLSID or the ProgID.

To find the Name, CLSID, and ProgID of an ESRI extension, refer to the following technical document:

ArcObjects Developer Help > Technical Documents > Names and IDs > Extensions

Specified by:

findExtension in interface IExtensionManager

Parameters:

nameOrID - A Variant (in)

Returns:

A reference to a com.esri.arcgis.system.IExtension

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

startupExtensions

public void startupExtensions(IUID componentCategory,
                              IUID jitCategory,
                              java.lang.Object initializationData)
                       throws java.io.IOException,
                              AutomationException

Description copied from interface: IExtensionManagerAdmin

Creates and starts the extensions for the given component category, passing initializationData to each in IExtension::Startup.

Supported Platforms

Windows, Solaris, Linux

Description

The StartupExtensions method is similar to AddExtension, except that it operates on all the extensions in the specified component category (for example, ESRI Mx Extensions).

Remarks

It is okay to add extensions to your Application using the AddExtension method after extensions were added with the StartupExtensions method.

You cannot add extensions to your Application using the StartupExtensions method after extensions were added with the AddExtension method. It evokes the "Automation error Catastrophic failure" (-2147418113).

The StartupExtensions method needs to be called before the AddExtensions method or used solely.

Specified by:

startupExtensions in interface IExtensionManagerAdmin

Parameters:

componentCategory - A reference to a com.esri.arcgis.system.IUID (in)

jitCategory - A reference to a com.esri.arcgis.system.IUID (in)

initializationData - A Variant (in)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

shutdownExtensions

public void shutdownExtensions()
                        throws java.io.IOException,
                               AutomationException

Description copied from interface: IExtensionManagerAdmin

Shuts down and releases the extensions that are loaded and calls IExtension::Shutdown.

Supported Platforms

Windows, Solaris, Linux

Description

The ShutdownExtensions method unloads all the extensions from your application and releases the licenses.

Remarks

There is no way to add extensions to your application using the same method, with which extensions were added to it, after the ShutdownExtensions method has been called in the same application lifetime.

Example 1:

Extensions were added with the AddExtension method.

The ShutdownExtensions has been called.

You cannot add extensions using the AddExtension method.

You can add extensions using the StartupExtensions method.

Example 2:

Extensions were added with the StartupExtensions method.

The ShutdownExtensions has been called.

You cannot add extensions using the StartupExtensions method.

You can add extensions using the AddExtension method.

Specified by:

shutdownExtensions in interface IExtensionManagerAdmin

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

addExtension

public void addExtension(IUID extensionCLSID,
                         java.lang.Object initializationData)
                  throws java.io.IOException,
                         AutomationException

Description copied from interface: IExtensionManagerAdmin

Creates a single extension given the CLSID, then passes initializationData to IExtension::Startup.

Supported Platforms

Windows, Solaris, Linux

Description

The AddExtension method loads the extension specified by the CLSID. Before using a licensed extension, it needs to be loaded and enabled.

extensionCLSID specifies the unique identifier (UID) of an extension.

To enable the extension, find the extension using the IExtensionManager::FindExtension method, obtain IExtensionConfig on the extension, and then set the State property to esriESEnabled.

To load all the extension within a specified component category (for example, ESRI Mx Extensions) use the StartipExtensions method.

Remarks

COM coclasses are identified by a globally unique identifier (GUID). There two formats for the GUID for a coclass: a class ID (CLSID) and a ProgID. The ProgID is a text alias for a CLSID. The UID coclass can be used to represent the GUID of an extension object. You can set the IUID.Value property to either the CLSID or the ProgID.

To find the CLSID and ProgID of an ESRI extension, refer to the following technical document:

ArcObjects Developer Help > Technical Documents > ESRI Extensions: Names and IDs

For your custom extensions, the ProgID is a string composed of the name of your project used to make the extension and the class name of the extension.

Specified by:

addExtension in interface IExtensionManagerAdmin

Parameters:

extensionCLSID - A reference to a com.esri.arcgis.system.IUID (in)

initializationData - A Variant (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

interfaceSupportsErrorInfo

public void interfaceSupportsErrorInfo(GUID riid)
                                throws java.io.IOException,
                                       AutomationException

Description copied from interface: ISupportErrorInfo

Supported Platforms

Windows, Solaris, Linux

Description

Indicates whether the interface supports IErrorInfo.

Specified by:

interfaceSupportsErrorInfo in interface ISupportErrorInfo

Parameters:

riid - A Structure: com.esri.arcgis.support.ms.stdole.GUID (in)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

getJITExtensionCount

public int getJITExtensionCount()
                         throws java.io.IOException,
                                AutomationException

Description copied from interface: IJITExtensionManager

The number of just in time extensions registered with the application.

Supported Platforms

Windows, Solaris, Linux

Description

Returns the number of JIT extensions currently in the application. This does not include any ordinary extensions.

Specified by:

getJITExtensionCount in interface IJITExtensionManager

Returns:

The pCount

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

getJITExtensionCLSID

public IUID getJITExtensionCLSID(int index)
                          throws java.io.IOException,
                                 AutomationException

Description copied from interface: IJITExtensionManager

Retrieves the CLSID of the JIT Extension at index.

Supported Platforms

Windows, Solaris, Linux

Description

Returns the UID of the JIT extension at the specifed index. The first JIT extension in the collection will have an index of 0 and the last JIT extension in the collection will have an index of JITExtentionCount - 1.

Specified by:

getJITExtensionCLSID in interface IJITExtensionManager

Parameters:

index - The index (in)

Returns:

A reference to a com.esri.arcgis.system.IUID

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isLoaded

public boolean isLoaded(IUID pID)
                 throws java.io.IOException,
                        AutomationException

Description copied from interface: IJITExtensionManager

Returns whether the extension is currently loaded.

Specified by:

isLoaded in interface IJITExtensionManager

Parameters:

pID - A reference to a com.esri.arcgis.system.IUID (in)

Returns:

The bLoaded

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

removeExtension

public void removeExtension(IExtension pExtension)
                     throws java.io.IOException,
                            AutomationException

Description copied from interface: IJITExtensionManager

Removes a just in time extension from the manager.

Supported Platforms

Windows, Solaris, Linux

Description

Removed the specified JIT extension from the ExtensionManager.

Specified by:

removeExtension in interface IJITExtensionManager

Parameters:

pExtension - A reference to a com.esri.arcgis.system.IExtension (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

insertExtension

public void insertExtension(IUID pExtCLSID,
                            IExtension pExtension)
                     throws java.io.IOException,
                            AutomationException

Description copied from interface: IJITExtensionManager

Adds an extension to the manager without initialization.

Supported Platforms

Windows, Solaris, Linux

Description

Adds the specified JIT extension to the ExtensionManager. Note that a JIT extension will be loaded the first time that IApplication::FindExtensionByCLSID is called for that extension.

Specified by:

insertExtension in interface IJITExtensionManager

Parameters:

pExtCLSID - A reference to a com.esri.arcgis.system.IUID (in)

pExtension - A reference to a com.esri.arcgis.system.IExtension (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isExtensionEnabled

public boolean isExtensionEnabled(IUID pExtCLSID)
                           throws java.io.IOException,
                                  AutomationException

Description copied from interface: IJITExtensionManager

Returns whether the extension is currently checked on.

Specified by:

isExtensionEnabled in interface IJITExtensionManager

Parameters:

pExtCLSID - A reference to a com.esri.arcgis.system.IUID (in)

Returns:

The enabled

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.