com.esri.arcgis.controls
Class LicenseControl

java.lang.Object
  java.awt.Component
      java.awt.Canvas
          com.esri.arcgis.interop.Ocx
              com.esri.arcgis.controls.LicenseControl

All Implemented Interfaces:

ILicenseControl, ILicenseControlDefault, IPersistStreamInit, com.esri.arcgis.interop.RemoteObjRef, IPersist, ISupportErrorInfo, ImageObserver, MenuContainer, Serializable, Accessible

public class LicenseControl
extends com.esri.arcgis.interop.Ocx
implements com.esri.arcgis.interop.RemoteObjRef, ILicenseControlDefault, ILicenseControl, IPersistStreamInit, IPersist, ISupportErrorInfo

Esri LicenseControl

Description

Use the LicenseControl to initialize each application with a suitable license(s) for it to run successfully on any machine it is deployed on to. The LicenseControl will configure the licenses at application start time when the form or dialog containing the LicenseControl is loaded.

All applications need to be configured with a license except when the application is not a stand-alone executable, i.e., if it's a DLL that will be incorporated into an application that will itself perform the license configuration.

There are two types of license to consider when initializing an application, product licenses and extension licenses, if an application uses any of the ArcGIS extensions. These licenses can be Engine Single Use, Desktop Single Use, or Desktop Concurrent licenses.

• Engine Single Use provides access to either the ArcGIS Engine or ArcGIS Engine Enterprise GeoDatabase licenses.
• Desktop Concurrent licenses provide access to the Desktop concurrent ArcGIS for Desktop Basic, ArcGIS for Desktop Standard, and ArcGIS for Desktop Advanced licenses.
• Desktop Single Use licenses use the same technology as Desktop Concurrent licenses and provide access to Single Use ArcGIS for Desktop Basic, ArcGIS for Desktop Standard, and ArcGIS Desktop for Advanced licenses. The LicenseControl does not differentiate between a Single Use and a Desktop Concurrent license, so they should be treated as the same.

Once an application has been initialized with a license, it cannot be re-initialized (with a new license); an application is initialized with a license for the duration of its life. When initializing an application with a license the following must be considered:

• The types of product license that the application can run with. For example, an enterprise geodatabase editing application will not be able to run with an ArcGIS Engine license or an ArcGIS for Desktop Basic license. However, it will be able to run with an ArcGIS Engine Enterprise GeoDatabase license, an ArcGIS for Desktop Standard license or an ArcGIS for Desktop Advanced license.
• The types of product license available to the application. For example, an application that can be run with an ArcGIS Engine license will also run with an ArcGIS for Desktop Basic, ArcGIS for Desktop Standard, and an ArcGIS for Desktop Advanced license. However, it may not be desirable to consume more than the minimum required license as doing so would lock the license for the lifetime of the application.
• Using an ArcGIS for Desktop Basic license on an ArcGIS Engine application will give you access to all the functionality available to a standard Engine license. Likewise, using an ArcGIS for Desktop Standard license on an ArcGIS Engine application will give you access to all the functionality available to an ArcGIS Engine Enterprise GeoDatabase license.

Use the LicenseControl to automatically perform license initialization within simple graphical user interface applications using the ArcGIS MapControl, PageLayoutControl, TOCControl, ToolbarControl, SymbologyControl, SceneControl, or GlobeControl. If greater control is required over license initialization, particularly when checking out and checking in extension licenses (the LicenseControl will check out extension licenses for the duration of an application's life), use the AoInitialize object to programmatically perform license initialization.

Using the LicenseControl in an application that programmatically initializes a product license is not recommended, because the LicenseControl may initialize a product license before the initialization code executes. However, the LicenseControl can be used to initialize an application with a product license, and any required extension licenses can be checked out and checked in programmatically.

Use the License Property Page to select the product licenses the application can be initialized with, select the extension licenses required by the application and to set whether the application is shutdown automatically if license initialization fails.

Products

Select at least one product license the application can be initialized with. By default, the LicenseControl will try to initialize the application with the ArcGIS Engine product license.

If the product you require is not licensed, you may optionally initialize the application with a higher product license. For example, if you select the ArcGIS Engine license and the ArcGIS for Desktop Basic license, the LicenseControl will initially try to initialize the application with an ArcGIS Engine license (the lower license). If that license is not available, the LicenseControl will try to initialize the application with an ArcGIS for Desktop Basic license (the next higher level license selected). If no product licenses are available, then the application will fail to initialize. Note, that once an application is initialized with a product license, it is not possible to re-initialize the application for the duration of the application's life.

Extensions

Select the extension licenses required by the application. Not every extension license is available with every product license, as such, the list of available extension licenses will change as different product licenses become selected. If the ArcGIS Engine product license is selected and an ArcGIS for Desktop product is selected, only the ArcGIS Engine extension licenses will display.

The availability of each extension license is checked in conjunction with the product license that the application will ultimately be initialized with. If any of the selected extensions are not available, the application will fail to initialize. The LicenseControl will check out extensions directly after the application is initialized and will check in extensions when the application is shutdown.

If a SceneControl or GlobeControl (requiring the 3D Analyst extension) is embedded within the same container as the LicenseControl, the 3D Analyst extension will automatically be checked.

Shutdown

Set whether the LicenseControl will automatically shut down the application if license initialization fails. If the LicenseControl handles license initialization failure, a 'License Failure' dialog box will be displayed to the user before the application is shutdown. If the developer handles license initialization failure, the ILicenseControl interface members can be used to obtain information on the nature of the failure before the application is programmatically shut down.

Product Availability

Available with ArcGIS Engine.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.awt.Canvas

Canvas.AccessibleAWTCanvas

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

Fields inherited from class com.esri.arcgis.interop.Ocx

rootParentContainers, rootWindows

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

LicenseControl()
Constructs a LicenseControl using ArcGIS Engine.

LicenseControl(Object o)
Constructs a LicenseControl.

Method Summary

void	aboutBox() Displays a dialog of information about the LicenseControl.
void	addNotify()
boolean	equals(Object o) Compare this object with another
void	getClassID(GUID[] pClassID) getClassID
static String	getClsid() getClsid.
String	getLicenseAvailability(int option) A Description of the availability of the licenses either all licenses or just those specified in the LicenseControls property page.
void	getSizeMax(_ULARGE_INTEGER[] pCbSize) getSizeMax
int	getStatus() The status of the LicenseControl initialization.
String	getSummary() A summary of the status of the LicenseControl initialization.
void	initNew() initNew
void	interfaceSupportsErrorInfo(GUID riid) interfaceSupportsErrorInfo
void	isDirty() isDirty
void	load(IStream pStm) load
void	save(IStream pStm, int fClearDirty) save
void	showStatusDialog(int hWndParent, int option, Object windowTitle, Object heading) Shows a dialog displaying the LicenseControl status and the current license availability.

Methods inherited from class com.esri.arcgis.interop.Ocx

checkIfVisible, dispose, finalize, getCanvasWindowHandle, getControlWindowHandle, getMinimumSize, getObjRef, getPreferredSize, paint, removeNotify, setBounds, setBounds, setSize, setSize, zz_doQueuedSets, zz_get, zz_get, zz_get, zz_get, zz_get, zz_get, zz_get, zz_get, zz_queueSet, zz_queueSet, zz_queueSet, zz_queueSet, zz_queueSet, zz_queueSet, zz_queueSet, zz_queueSet

Methods inherited from class java.awt.Canvas

createBufferStrategy, createBufferStrategy, getAccessibleContext, getBufferStrategy, update

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate

Methods inherited from class java.lang.Object

clone, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.esri.arcgis.interop.RemoteObjRef

getJintegraDispatch, release

Constructor Detail

LicenseControl

public LicenseControl()

Constructs a LicenseControl using ArcGIS Engine.

LicenseControl

public LicenseControl(Object o)

Constructs a LicenseControl.

Method Detail

getClsid

public static String getClsid()

getClsid.

equals

public boolean equals(Object o)

Compare this object with another

Overrides:

equals in class Object

addNotify

public void addNotify()

Overrides:

addNotify in class com.esri.arcgis.interop.Ocx

aboutBox

public void aboutBox()
              throws IOException,
                     AutomationException

Displays a dialog of information about the LicenseControl.

Description

The AboutBox method causes a modal dialog box to display on top of the LicenseControl, containing information about the version and creation date of the LicenseControl as well as listing relevant legal and copyright information from ESRI.

Product Availability

Available with ArcGIS Engine.

Specified by:

aboutBox in interface ILicenseControl

Specified by:

aboutBox in interface ILicenseControlDefault

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getStatus

public int getStatus()
              throws IOException,
                     AutomationException

The status of the LicenseControl initialization.

Description

Returns the Status of the LicenseControl when it initially tried to initilaize the application. If license initailization was successful the Status will return esriLicenseCheckedOut.

Remarks

If no product licenses were checked in the LicenseControl property pages, the Status returns esriLicenseFailure.

Product Availability

Available with ArcGIS Engine.

Specified by:

getStatus in interface ILicenseControl

Specified by:

getStatus in interface ILicenseControlDefault

Returns:

A com.esri.arcgis.system.esriLicenseStatus constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getSummary

public String getSummary()
                  throws IOException,
                         AutomationException

A summary of the status of the LicenseControl initialization.

Description

Returns a summary of the license status after the LicenseControl has tried to initialize the application with a license. Use the Summary property when license initialization fails, to give information to the user on the nature of the failure, before programmatically shutting down the application.

The possible descriptions returned from the Summary property are as follows:
- "Successful license initialization."
- "No licenses were requested."
- "Failed to initialize license, required products are not available."
- "Failed to initialize license, required extensions are not available."
- "Failed to initialize product license."
- "Failed to checkout extension license."

Remarks

The default behaviour of the LicenseControl is to allow the developer to programmatically check for and shutdown an application when license initialization fails. To override this behaviour so the LicenseControl automatically shuts down an application when license initialization fails, check the "Shutdown this application if the selected licenses are not available" check box in the property pages of the LicenseControl.

Product Availability

Available with ArcGIS Engine.

Specified by:

getSummary in interface ILicenseControl

Specified by:

getSummary in interface ILicenseControlDefault

Returns:

The returnValue

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getLicenseAvailability

public String getLicenseAvailability(int option)
                              throws IOException,
                                     AutomationException

A Description of the availability of the licenses either all licenses or just those specified in the LicenseControls property page.

Product Availability

Available with ArcGIS Engine.

Specified by:

getLicenseAvailability in interface ILicenseControl

Specified by:

getLicenseAvailability in interface ILicenseControlDefault

Parameters:

option - A com.esri.arcgis.controls.esriLicenseStatusOptions constant (in, optional, pass 1 if not required)

Returns:

The returnValue

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

showStatusDialog

public void showStatusDialog(int hWndParent,
                             int option,
                             Object windowTitle,
                             Object heading)
                      throws IOException,
                             AutomationException

Shows a dialog displaying the LicenseControl status and the current license availability.

Description

Opens a modal dialog specifying the current availability of the specified product and extension licenses. Use the ShowStatusDialog method when license initialization fails, to give information to the user on the nature of the failure, before programmatically shutting down the application. Alternatively, use the Status, Summary and LicenseAvailability members to create your own dialog.

esriLicenseStatusRequested returns the availability of those product and extension licenses checked in the LicenseControl property pages. Use this option when license initialization fails, to give information to the user on the nature of the failure, before programmatically shutting down the application.

esriLicenseStatusAll returns the availability of all product and extension licenses. Use this option when debugging.

By default the modal dialog will have a window title of "License Status" and a heading of "Requested License Status".

Remarks

The default behaviour of the LicenseControl is to allow the developer to programmatically check for and shutdown an application when license initialization fails. To override this behaviour so the LicenseControl automatically shuts down an application when license initialization fails, check the "Shutdown this application if the selected licenses are not available" check box in the property pages of the LicenseControl.

Product Availability

Available with ArcGIS Engine.

Specified by:

showStatusDialog in interface ILicenseControl

Specified by:

showStatusDialog in interface ILicenseControlDefault

Parameters:

hWndParent - The hWndParent (in, optional, pass 0 if not required)

option - A com.esri.arcgis.controls.esriLicenseStatusOptions constant (in, optional, pass 1 if not required)

windowTitle - A Variant (in, optional, pass null if not required)

heading - A Variant (in, optional, pass null if not required)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

isDirty

public void isDirty()
             throws IOException,
                    AutomationException

isDirty

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

isDirty in interface IPersistStreamInit

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

load

public void load(IStream pStm)
          throws IOException,
                 AutomationException

load

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

load in interface IPersistStreamInit

Parameters:

pStm - A reference to a com.esri.arcgis.system.IStream (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

save

public void save(IStream pStm,
                 int fClearDirty)
          throws IOException,
                 AutomationException

save

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

save in interface IPersistStreamInit

Parameters:

pStm - A reference to a com.esri.arcgis.system.IStream (in)

fClearDirty - The fClearDirty (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getSizeMax

public void getSizeMax(_ULARGE_INTEGER[] pCbSize)
                throws IOException,
                       AutomationException

getSizeMax

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

getSizeMax in interface IPersistStreamInit

Parameters:

pCbSize - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (out: use single element array)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

initNew

public void initNew()
             throws IOException,
                    AutomationException

initNew

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

initNew in interface IPersistStreamInit

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getClassID

public void getClassID(GUID[] pClassID)
                throws IOException,
                       AutomationException

getClassID

Description

IPersist is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

getClassID in interface IPersist

Parameters:

pClassID - A Structure: com.esri.arcgis.support.ms.stdole.GUID (out: use single element array)

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.