com.esri.arcgis.system
Class AoInitialize

java.lang.Object
  extended by 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 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:

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.

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:

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.

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

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.