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 an application is initialized with a Desktop Concurrent license, the application will subsequently only be able to access that Desktop Concurrent license server and its extension licenses.
• If an application is initialized with a Desktop Single Use license, the application will subsequently only be able to access that single use license server and its extension licenses.
• If an application is initialized with the Engine Single Use license on your machine, the application will subsequently only be able to access the Engine Single Use extension licenses.

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:

• the license is unavailable because it is already being used (Desktop Concurrent licenses only).
• an unexpected license failure occurs due to system administration problems.
• the license is already initialized. An application is initialized with a product license for the duration of it life. Use the InitializedProduct method to determine what license an application is initialized with.

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.

• If the application was initialized with either of the Engine Single Use licenses, any extensions used by the application will also be Engine Single Use. As such, any extensions can be checked out directly after the application is initialized and checked back in before Shutdown.
• If the application was initialized with a license server and the extensions are required by the application for it to run successfully, the extensions should be checked out directly after the application is initialized and checked back in before Shutdown.
• If the application was initialized with a license server and the extension functionality is not necessary for the application to function, the extensions can either be checked out directly after the application is initialized or checked out as and when the extension functionality is required. When the extension is checked in, the functionality should be disabled. Use the IsExtensionCheckedOut method to determine whether the extension is already checked out.

Using the CheckOutExtension method to check out an extension in an ArcGIS for 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:

• the extension is not licensed.
• the license is unavailable because it is already being used. An extension may fail to check out because it may have been checked out by another application since the IsExtensionCodeAvailable method checked its availability. (Desktop Concurrent licenses only).
• an unexpected license failure occurs due to system administration problems.
• the license is already checked out. Use the IsExtensionCheckedOut method to determine this.

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.

• If the application was initialized with either of the Engine Single Use licenses, any extensions used by the application will also be Engine Single Use. As such any extensions can be checked out directly after the application is initialized and checked back in before Shutdown.
• If the application was initialized with a license server and the extensions are required by the application for it to run successfully, the extensions should be checked out directly after the application is initialized and checked back in before Shutdown.
• If the application was initialized with a license server and the extension functionality is not necessary for the application to function, the extensions can either be checked out directly after the application is initialized or checked out as and when the extension functionality is required. When the extension is checked in the functionality should be disabled. Use the IsExtensionCheckedOut method determines whether the extension is already checked out.

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 ArcGIS for Desktop Standard or an ArcGIS for Desktop Advanced license, the editing functionality can be enabled. If, however, the application has been initialized with an Engine Single Use or ArcGIS for Desktop Basic 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.