com.esri.arcgis.controls
Class LicenseControl

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Canvas
          extended by com.esri.arcgis.interop.Ocx
              extended by 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.

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:

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.