com.esri.arcgis.system
Class AoInitialize

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

All Implemented Interfaces:

com.esri.arcgis.interop.RemoteObjRef, IAoInitialize, ILicenseInformation, ISupportErrorInfo, Serializable

public class AoInitialize
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, IAoInitialize, ISupportErrorInfo, ILicenseInformation

Class initializes ArcObject components runtime environment. This class must be the first ArcObject created.

See Also:

Serialized Form

Constructor Summary

AoInitialize()
Constructs a AoInitialize on the local host.

AoInitialize(com.esri.arcgis.interop.AuthInfo authInfo)
Deprecated. use AuthInfo.setDefault(...) or AuthInfo.setThreadDefault(...) Please see Security section in the J-Integra for COM documentation

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

AoInitialize(String host)
Construct a AoInitialize on specified host.

AoInitialize(String host, com.esri.arcgis.interop.AuthInfo authInfo)
Deprecated. use AuthInfo.setDefault(...) or AuthInfo.setThreadDefault(...) See Security section in the J-Integra for COM documentation

Method Summary

static AoInitialize	bindUsingMoniker(String moniker) bindUsingMoniker.
int	checkInExtension(int extensionCode) Check in an extension.
int	checkOutExtension(int extensionCode) Check out an extension.
boolean	equals(Object o) Compare this object with another
static AoInitialize	getActiveObject() getActiveObject.
static String	getClsid()
com.esri.arcgis.interop.Dispatch	getJintegraDispatch() J-Integra for COM internal method
protected String	getJintegraVersion()
String	getLicenseExtensionName(int extensionCode) Retrieve the name license extension code.
String	getLicenseProductName(int productCode) Retrieve the name license product code.
ILicenseInfoEnum	getProductExtensions(int productCode) Enumerate the extensions supported the product.
Object	getPropertyByName(String name) getPropertyByName.
Object	getPropertyByName(String name, Object rhs) getPropertyByName.
int	hashCode() the hashcode for this object
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.
void	interfaceSupportsErrorInfo(GUID riid) interfaceSupportsErrorInfo
Object	invokeMethodByName(String name) invokeMethodByName.
Object	invokeMethodByName(String name, Object[] parameters) invokeMethodByName.
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	release() Release a AoInitialize.
void	shutdown() Shutdown method.

Methods inherited from class java.lang.Object

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

Constructor Detail

AoInitialize

public AoInitialize()
             throws IOException,
                    UnknownHostException

Constructs a AoInitialize on the local host.

Throws:

IOException - if there are problems communicating via DCOM

UnknownHostException - if the host can not be found

AoInitialize

public AoInitialize(String host)
             throws IOException,
                    UnknownHostException

Construct a AoInitialize on specified host.

Parameters:

host - the host on which the object should be created

Throws:

IOException - if there are problems communicating via DCOM

UnknownHostException - if the host can not be found

AoInitialize

public AoInitialize(com.esri.arcgis.interop.AuthInfo authInfo)
             throws IOException,
                    UnknownHostException

Deprecated. use AuthInfo.setDefault(...) or AuthInfo.setThreadDefault(...) Please see Security section in the J-Integra for COM documentation

Throws:

IOException

UnknownHostException

See Also:

com.esri.arcgis.interop.AuthInfo.setDefault(..)

AoInitialize

public AoInitialize(String host,
                    com.esri.arcgis.interop.AuthInfo authInfo)
             throws IOException,
                    UnknownHostException

Deprecated. use AuthInfo.setDefault(...) or AuthInfo.setThreadDefault(...) See Security section in the J-Integra for COM documentation

Throws:

IOException

UnknownHostException

See Also:

com.esri.arcgis.interop.AuthInfo.setDefault(..)

AoInitialize

public AoInitialize(Object obj)
             throws IOException

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

Construct a AoInitialize using a reference to such an object returned from a COM server

Parameters:

obj - an object returned from a COM server

Throws:

IOException - if there are problems communicating via DCOM

Method Detail

getClsid

public static String getClsid()

getJintegraVersion

protected String getJintegraVersion()

equals

public boolean equals(Object o)

Compare this object with another

Overrides:

equals in class Object

hashCode

public int hashCode()

the hashcode for this object

Overrides:

hashCode in class Object

getActiveObject

public static AoInitialize getActiveObject()
                                    throws AutomationException,
                                           IOException

getActiveObject. Get a reference to a running instance of this class on the current machine using native code. Uses native code (See GetActiveObject() in MS doc) and thus can only be used on MS Windows

Returns:

A reference to the running object.

Throws:

IOException - If there are communications problems.

AutomationException - If there was an error attaching to the instance.

bindUsingMoniker

public static AoInitialize bindUsingMoniker(String moniker)
                                     throws AutomationException,
                                            IOException

bindUsingMoniker. Bind to a running instance of this class using the supplied ObjRef moniker

Parameters:

moniker - The ObjRef Moniker (Created using Windows CreateObjrefMoniker() and IMoniker->GetDisplayName).

Returns:

A reference to the running object.

Throws:

IOException - If there are communications problems.

AutomationException - If there was an error attaching to the instance.

getJintegraDispatch

public com.esri.arcgis.interop.Dispatch getJintegraDispatch()

J-Integra for COM internal method

Specified by:

getJintegraDispatch in interface com.esri.arcgis.interop.RemoteObjRef

release

public void release()

Release a AoInitialize.

Specified by:

release in interface com.esri.arcgis.interop.RemoteObjRef

getPropertyByName

public Object getPropertyByName(String name)
                         throws NoSuchFieldException,
                                IOException,
                                AutomationException

getPropertyByName. Get the value of a property dynamically at run-time, based on its name

Parameters:

name - The name of the property to get.

Returns:

The value of the property.

Throws:

NoSuchFieldException - If the property does not exit.

IOException - If there are communications problems.

AutomationException - If the remote server throws an exception.

getPropertyByName

public Object getPropertyByName(String name,
                                Object rhs)
                         throws NoSuchFieldException,
                                IOException,
                                AutomationException

getPropertyByName. Get the value of a property dynamically at run-time, based on its name and a parameter

Parameters:

name - The name of the property to get.

rhs - A parameter used when getting the proxy.

Returns:

The value of the property.

Throws:

NoSuchFieldException - If the property does not exit.

IOException - If there are communications problems.

AutomationException - If the remote server throws an exception.

invokeMethodByName

public Object invokeMethodByName(String name,
                                 Object[] parameters)
                          throws NoSuchMethodException,
                                 IOException,
                                 AutomationException

invokeMethodByName. Invoke a method dynamically at run-time

Parameters:

name - The name of the method to be invoked.

parameters - One element for each parameter. Use primitive type wrappers. to pass primitive types (eg Integer to pass an int).

Returns:

The value returned by the method (null if none).

Throws:

NoSuchMethodException - If the method does not exit.

IOException - If there are communications problems.

AutomationException - If the remote server throws an exception.

invokeMethodByName

public Object invokeMethodByName(String name)
                          throws NoSuchMethodException,
                                 IOException,
                                 AutomationException

invokeMethodByName. Invoke a method dynamically at run-time

Parameters:

name - The name of the method to be invoked.

Returns:

The value returned by the method (null if none).

Throws:

NoSuchMethodException - If the method does not exit.

IOException - If there are communications problems.

AutomationException - If the remote server throws an exception.

isProductCodeAvailable

public 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

Specified by:

isProductCodeAvailable in interface IAoInitialize

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

public 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

Specified by:

isExtensionCodeAvailable in interface IAoInitialize

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

public 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

Specified by:

initialize in interface IAoInitialize

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

public 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 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:

• 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

Specified by:

checkOutExtension in interface IAoInitialize

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

public 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

Specified by:

checkInExtension in interface IAoInitialize

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

public 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

Specified by:

shutdown in interface IAoInitialize

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

initializedProduct

public 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

Specified by:

initializedProduct in interface IAoInitialize

Returns:

A com.esri.arcgis.system.esriLicenseProductCode constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isExtensionCheckedOut

public 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

Specified by:

isExtensionCheckedOut in interface IAoInitialize

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.

interfaceSupportsErrorInfo

public void interfaceSupportsErrorInfo(GUID riid)
                                throws IOException,
                                       AutomationException

interfaceSupportsErrorInfo

Description

Indicates whether the interface supports IErrorInfo.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

interfaceSupportsErrorInfo in interface ISupportErrorInfo

Parameters:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getLicenseProductName

public String getLicenseProductName(int productCode)
                             throws IOException,
                                    AutomationException

Retrieve the name license product code.

Description

Returns the name of the specified license product code constant.

Product Availability

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

Specified by:

getLicenseProductName in interface ILicenseInformation

Parameters:

productCode - A com.esri.arcgis.system.esriLicenseProductCode constant (in)

Returns:

The productName

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getLicenseExtensionName

public String getLicenseExtensionName(int extensionCode)
                               throws IOException,
                                      AutomationException

Retrieve the name license extension code.

Description

Returns the name of the specified license extension code constant.

Product Availability

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

Specified by:

getLicenseExtensionName in interface ILicenseInformation

Parameters:

extensionCode - A com.esri.arcgis.system.esriLicenseExtensionCode constant (in)

Returns:

The extensionName

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getProductExtensions

public ILicenseInfoEnum getProductExtensions(int productCode)
                                      throws IOException,
                                             AutomationException

Enumerate the extensions supported the product.

Description

Returns an ILicenseInfoEnum collection of license extension codes supported by the specified license product code. Note that all supported extension codes are returned and not just the ones available on the current license server.

Product Availability

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

Specified by:

getProductExtensions in interface ILicenseInformation

Parameters:

productCode - A com.esri.arcgis.system.esriLicenseProductCode constant (in)

Returns:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.