com.esri.arcgis.system
Interface IAoInitialize

All Superinterfaces:
Serializable
All Known Implementing Classes:
AoInitialize

public interface IAoInitialize
extends Serializable

Provides access to members that initialize licensing for ArcGIS Desktop, Engine, and Server.

Description

The IAoInitialize Interface is the starting point for developers to initialize each application with a suitable license(s) in order for it to run successfully on any machine it is deployed on to. License configuration must be undertaken at application start time, before any ArcObjects are accessed. Failure to do so will result in application errors.

Product Availability

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


Method Summary
 int checkInExtension(int extensionCode)
          Check in an extension.
 int checkOutExtension(int extensionCode)
          Check out an extension.
 int initialize(int productCode)
          This must be called before any other ArcObjects are created to initialize product Code.
 int initializedProduct()
          Retrieve's the product code at which the application has been initialized.
 boolean isExtensionCheckedOut(int extensionCode)
          Is the Extension checked out.
 int isExtensionCodeAvailable(int productCode, int extensionCode)
          Check if the Product Code is available and then the Extension Code for that product.
 int isProductCodeAvailable(int productCode)
          Check if the Product Code is available.
 void shutdown()
          Shutdown method.
 

Method Detail

isProductCodeAvailable

int isProductCodeAvailable(int productCode)
                           throws IOException,
                                  AutomationException
Check if the Product Code is available.

Description

The IsProductCodeAvailable method returns whether the specified license is available. If the license is available it can be used to Initialize the application.

If the product you require is not available you may want to check whether a higher product license is available to Initialize the application with. If the license you require is available using Engine Single Use then we recommend you use it in preference to the Desktop Concurrent and Desktop Single Use licenses. This means you will not limit the Desktop Concurrent licenses available to any other users. If there are no appropriate product licenses available the application should inform the user of the issue, and either allow the user to resolve the issue or exit the application.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
productCode - A com.esri.arcgis.system.esriLicenseProductCode constant (in)
Returns:
A com.esri.arcgis.system.esriLicenseStatus constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isExtensionCodeAvailable

int isExtensionCodeAvailable(int productCode,
                             int extensionCode)
                             throws IOException,
                                    AutomationException
Check if the Product Code is available and then the Extension Code for that product.

Description

The IsExtensionCodeAvailable method returns whether the specified extension license is available with the specified product license that will be used to Initialize the application (not every extension license is available with every product license). The method firstly checks the availability of the product license and secondly checks the availability of the extension license with the product license.

When an application is initialized with a particular product license, a connection is made to a license server. All subsequent calls to the CheckOutExtension and CheckInExtension methods are made to the same license server. As such, you cannot use a combination of licenses from difference license servers or Engine Single Use.

If the licenses you require are available using Engine Single Use then we recommend you use it in preference to the Desktop Concurrent and Desktop Single Use licenses. This means you will not limit the Desktop Concurrent licenses available to any other users.

If an extension required by the application for it to run successfully is not available, the application should inform the user of the issue, and exit the application. If the extension functionality is not necessary for the application to function, and the extension license is unavailable, the application should disable to the user the functionality dependant upon the extension.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
productCode - A com.esri.arcgis.system.esriLicenseProductCode constant (in)
extensionCode - A com.esri.arcgis.system.esriLicenseExtensionCode constant (in)
Returns:
A com.esri.arcgis.system.esriLicenseStatus constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

initialize

int initialize(int productCode)
               throws IOException,
                      AutomationException
This must be called before any other ArcObjects are created to initialize product Code. If called a second time during the life time of an executable with a new product code, it will return esriLicenseAlreadyInitialized.

Description

Initializes the appliction with the specified product license. The product license determines the functionality the application will be able to access. Once the product license has been initialized it cannot be changed for the duration of the applications life, as it is not possible to re-initialize the applicaiton.

Before initializing the application use the IsProductCodeAvailable and IsExtensionCodeAvailable methods to ensure the appropriate license(s) is available to Initialize the application with. If all the licenses you require are available using Engine Single Use then we recommend you use it in preference to the Desktop Concurrent and Desktop Single Use licenses. This means you will not limit the Desktop Concurrent licenses available to any other users.

Remarks

The Initialize method will fail to check out the specified product license if:

Note that loading data into the MapControl or PageLayoutControl through the property pages will automatically initialize the application with a product license. To ensure that the application is initialized with the product license specified by the Initialize method load data into the MapControl and PageLayoutControl programmatically after license initialization.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
productCode - A com.esri.arcgis.system.esriLicenseProductCode constant (in)
Returns:
A com.esri.arcgis.system.esriLicenseStatus constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

checkOutExtension

int checkOutExtension(int extensionCode)
                      throws IOException,
                             AutomationException
Check out an extension.

Description

Checks out the specified extension license. Extensions can either be checked out as and when an application requires the extension functionality, and checked in once the application has finished with the functionality; or the extension can be checked out directly after the application is initialized and checked back in before Shutdown. Use the CheckInExtension method to check extensions back in. The way that the extensions are checked in and out will depend on the type of product license passed to the Initialize method.

Using the CheckOutExtension method to check out an extension in a ArcGIS desktop application will not enable the user interface objects in the extension. Use the IExtension object to access the extension functionality and limit the use of the AoInitialize object to testing the availability of extension licenses and determining the extensions already checked out.

Remarks

If an application using extension functionality is initialized with an Engine single use license (ArcGIS Engine or ArcGIS Engine with Enterprise GeoDatabase) the extension license may automatically get checked out. This is because Engine single use licenses are not reference counted. It is highly recommended that extension licenses are always explicitly checked out using the CheckOutExtension method to support deployment of the application in both an environment that uses an Engine single use license and an environment that uses a license server (desktop single use or desktop concurrent licenses).

The CheckOutExtension method will fail to check out the specified extension license if:

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
extensionCode - A com.esri.arcgis.system.esriLicenseExtensionCode constant (in)
Returns:
A com.esri.arcgis.system.esriLicenseStatus constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

checkInExtension

int checkInExtension(int extensionCode)
                     throws IOException,
                            AutomationException
Check in an extension.

Description

Checks in the specified extension license once it has been checked out with the CheckOutExtension method.

The way that the extensions are checked in and out will depend on the type of product license passed to the Initialize method.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
extensionCode - A com.esri.arcgis.system.esriLicenseExtensionCode constant (in)
Returns:
A com.esri.arcgis.system.esriLicenseStatus constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

shutdown

void shutdown()
              throws IOException,
                     AutomationException
Shutdown method. This should be the last call to ArcObjects in an application.

Description

Before an application is shut down the AOInitialize object must be shut down. This ensures that any ESRI libraries that have been used are unloaded in the correct order. Failure to do this may result in random crashes on exit due to the operating system unloading the libraries in the incorrect order.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

initializedProduct

int initializedProduct()
                       throws IOException,
                              AutomationException
Retrieve's the product code at which the application has been initialized.

Description

The InitializedProduct method returns the product license that was passed to the Initialize method.

Checking what product license an application has been initialized with is useful for setting the enabled state of an applications functionality. For example, if an application containing some enterprise GeoDatabase editing has been initialized with an Engine Single Use with GeoDatabase Editing or an ArcEditor or an ArcInfo license, the editing functionality can be enabled. If however the application has been initialized with an Engine Single Use or ArcView license the editing functionality must be disabled

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Returns:
A com.esri.arcgis.system.esriLicenseProductCode constant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isExtensionCheckedOut

boolean isExtensionCheckedOut(int extensionCode)
                              throws IOException,
                                     AutomationException
Is the Extension checked out.

Description

Indicates whether the specified extension license is currently checked out. Extension licensess are checked out and in using CheckOutExtension and CheckInExtension methods.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Parameters:
extensionCode - A com.esri.arcgis.system.esriLicenseExtensionCode constant (in)
Returns:
The checkedOut
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.