# handle.java

    /*
    ** Module   : handle.java
    ** Abstract : Progress 4GL compatible handle object
    **
    ** Copyright (c) 2005-2025, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- --JPRM-- -----------------------------------Description----------------------------------
    ** 001 GES 20051125   @23505 Created initial version which represents
    **                           the Progress handle data type.
    ** 002 GES 20060206   @24300 Made compareTo() safe to process any object
    **                           type (avoids ClassCastException).
    ** 003 GES 20060208   @24390 Added a default format string getter.
    ** 004 GES 20060724   @28161 Added a forced assign() abstract method.
    ** 005 GES 20060807   @28479 Moved to externalizable interface to optimize
    **                           network performance. Throw an exception if
    **                           an attempt is made to serialize this class
    **                           since it makes no sense to transfer this
    **                           between systems.
    ** 006 GES 20070219   @32175 Added support for the widget-handle built-in
    **                           function.
    ** 007 GES 20070221   @32195 Added support for the TransparentWrapper as
    **                           a contained object that exposes its
    **                           referenced object instead.
    ** 008 GES 20080402   @37825 Added a new assign(Object) signature and a
    **                           new constructor handle(WrappedResource).
    ** 009 CA  20090227   @41383 Undefined SELF or FOCUS handles refers a
    **                           NullWidget instance - modified the isUnknown
    **                           method to return true when the referenced
    **                           value is not null, but unknown.
    ** 010 ECF 20101003          Removed ContextContainer inner class; replaced with
    **                           parameterized use of ContextLocal. Fixed javadoc.
    ** 011 CA  20130112          Major rework to implement generic handles.
    **                           Added c'tor which builds a new instance from a
    **                           BaseDataType value, if possible. This should be
    **                           used only when constructing an instance using the
    **                           value returned by a DYNAMIC-FUNCTION call; 4GL
    **                           does some special casting in this case, which is
    **                           not implemented yet.
    ** 012 EVL 20130130          Adding wrap methods to invoke DOM XML object
    **                           method calls. The new supported class: XEntity,
    **                           XNodeRef and XDocument.
    ** 013 CS 20130204           Added conversion support for socket and
    **                           server-socket.
    ** 014 VMN 20130207          Added unwrapBuffer(), unwrapQuery(), unwrapFieldInterface()
    ** 015 OM  20130129          Added TempTable handle unwrapper.
    ** 016 EVL 20130208          Adding wrap methods to invoke SAX object method calls. The new
    **                           supported class: XCommon, SaxEntity, SaxAttributes, SaxReader and
    **                           SaxWriter.
    ** 017 CA  20130216          Added unwrappers for SOAP-related handles.
    ** 018 CS  20130218          Added conversion support for app server.
    ** 019 VMN 20130219          Added support for attributes
    **                           ERROR (KW_ERROR)
    **                           NAME (KW_NAME)
    **                           PRIVATE-DATA (KW_PRIV_DAT)
    **                           DATA-TYPE (KW_DATATYPE)
    **                           LABEL (KW_LABEL)
    **                           DBNAME (KW_DBNAME)
    **                           TABLE (KW_TABLE)
    **                           WIDTH-CHARS (KW_WIDTH_C)
    **                           HEIGHT-CHARS (KW_HEIGHT_C)
    **                           WIDTH-PIXELS (KW_WIDTH_P)
    **                           HEIGHT-PIXELS (KW_HEIGHT_P)
    ** 020 CA  20130221          Reordered unwrap APIs. getType was renamed to getResourceType. Added
    **                           unwrap APIs for NAMESPACE-URI, UNIQUE-ID, ADM-DATA, CommonField and
    **                           Sizeable.
    ** 021 OM  20130220          Added dereference static methods for :: punctuation conversion.
    ** 022 OM  20130304          Refactored isValid and isUnknown of WrappedResource to valid
    **                           and unknown.
    ** 023 OM  20130320          Added ResultListHandler to the list of unwrapped interfaces.
    ** 024 CS  20130321          Added ConnectableServer to the list of unwrapped interfaces.
    ** 025 GES 20130322          Fixed the BDT c'tor and modified the assign(BDT,boolean) to be the
    **                           common location for the _POLY morphing. This is safe because all
    **                           current usage would have generated a ClassCastException if that
    **                           method was ever used with an invalid type. Now, instead of the CCE,
    **                           the code will morph the value as is possible. The morphing code
    **                           still needs to be implemented.
    ** 026 CA  20130529          Remove procedure-related dependencies, exposed the wrapped resource
    **                           via a getter.
    ** 027 OM  20130618          Use default constructor for unknown values of date. Cleanup.
    ** 028 CA  20130813          Added support for the async request handle.
    ** 029 CA  20130908          When obtaining the resource ID via resourceId(), make sure the
    **                           resource can be "restored" using the ID.
    ** 030 CA  20130919          Resource cleanup must be done after it was deleted.
    ** 031 EVK 20130909          Adding wrap methods to invoke DOM XML object method calls. The
    **                           new supported class: XmlSchema, Encoding. Make readOnlyError do not
    **                           set Error flag
    ** 032 CA  20130930          Added c'tor to instantiate a handle from a frame.
    ** 033 EVL 20131014          Changed the getting attribute name approach to be based on annotation
    **                           approach.
    ** 034 CA  20131021          Adds unwrapper for the DYNAMIC attribute.
    ** 035 CA  20131028          Fixed error message when a method is called on an invalid handle.
    ** 036 HC  20131031          Changed resource ID data type to Long, IDs are allocated instead of
    **                           derived from progress resources' hash codes, cleanup of allocated
    **                           resources, see issue #2183.
    ** 037 CA  20131013          Added INSTANTIATING-PROCEDURE support. Fixed assignment of frame
    **                           resources (as GenericFrame is no longer the legacy resource).
    ** 038 EVK 20131130          Added util method isHandleTypeOf. Fixed javadoc issues
    ** 039 CA  20140120          Fixed an error for APPLY statement using an unknown handle.
    ** 040 VMN 20140123          Cosmetic change to fit to 4GL message.
    ** 041 CA  20140218          Error messages use the program name as it was used at the RUN call.
    ** 042 CA  20140326          Added knownResource.
    ** 043 VIG 20140314          Added unwrapIterableResource() method to support IterableResource.
    ** 044 CA  20140526          unwrap APIs were switched to instance method calls.
    ** 045 CA  20140513          Added a weight for the context-local var, to ensure predetermined
    **                           order during context reset.
    ** 046 MAG 20140602          Fixed the BDT c'tor and modified the assign(BDT,boolean) on _POLY
    **                           morphing. Improved compareTo by comparing this handle with other BDT
    **                           types. Added a method to get the resource id if any as Long value.
    ** 047 VMN 20140702          Fixed InstantiationException in InvalidAttributeAccess.invoke().
    ** 048 CA  20140703          Added unwrapFontTable.
    ** 049 MAG 20140812          Added unwrapColorTable, unwrapNumEntries.
    ** 050 VIG 20140709          Set code2 var in InvalidAttributeAccess subclass.
    ** 051 SVL 20141102          Added some browse-related unwrap* functions.
    ** 052 GES 20141028          Added LegacyLogManager support.
    ** 053 GES 20141124          Added unwrapping for EditorInterface, InnerLines, QueryAssociable,
    **                           NumItems and ScrollbarHorizontalElement.
    ** 054 CA  20150122          APPLY ... TO <handle> is converted to LogicalTerminal APIs (code
    **                           related to it was removed).
    ** 055 EVL 20150128          Adding unwrapping for ImageSupport, ImageButtonSupport interfaces.
    ** 056 VIG 20150130          Added method unwrapMenu.
    ** 057 EVL 20150223          Adding unwrapping for ImageWidgetSupport.
    ** 058 IAS 20150224          Adding unwrapping for ConrolEntity interface.
    ** 059 EVL 20150227          Changing ImageButtonSupport to ButtonInterface.
    ** 060 ECF 20150315          Replaced FieldInterface with BufferField.
    ** 061 IAS 20150225          Added unwrapping for the BoxInterface
    ** 062 CA  20150416          Added unwrapTree, for the FIRST/LAST-CHILD attributes.
    ** 063 CA  20150502          The resource ID needs to be kept at the resource, so it can be
    **                           accessed after the resource is deleted.
    ** 064 IAS 20150604          Added ReplaceInterface and SelectableText.
    ** 065 SVL 20150804          Added unwrapDown and unwrapMultiple.
    ** 066 IAS 20150805          Added DeblankInterface, BlankInterface, PasswordFieldInterface
    **                           and IndexedInterface.
    ** 067 VIG 20150818          Added unwrapMenuItem method.
    ** 068 EVL 20150825          Adding SelectionListInterface unwrapper.
    ** 069 EVL 20150911          Adding OrientationInterface and SliderInterface unwrappers.
    ** 070 IAS 20150926          Adding TopOnlyInterface unwrapper.
    ** 071 OM  20150923          Removed Interface from unwrapper method names.
    ** 072 SVL 20151129          Added unwrapLabels().
    ** 073 CA  20151230          When creating an ID for an invalid resource, log the stacktrace only
    **                           if FINE logging is enabled.
    ** 074 HC  20160222          Fixed handle unwrapping in readOnlyError().
    ** 075 CA  20160327          Added support for LAST-EVENT:X and LAST-EVENT:Y attributes.
    ** 076 SBI 20160516          Added unwrapClipboard.
    ** 077 GES 20160617          Added unknown literal processing for the polymorphic assign case.
    ** 078 SVL 20160709          Added unwrapIndexInformation.
    ** 079 CA  20160627          Reworked undoable support - the undoables register themselves with
    **                           all blocks up the stack, until either 1. the tx block which created
    **                           it is reached or 2. the last tx block where it was saved is reached.
    ** 080 GES 20160909          Added unwrapping for RectangleInterface.
    ** 081 SBI 20160824          Added an automatic string to handle type conversion.
    ** 082 SVL 20170126          Added isValidEvent and unwrapRcodeInfo.
    **     OM  20170208          Replaced displayError to recordOrShowError in InvalidAttributeAccess.
    **     CA  20170228          Added APIs related to ExternalResource support.
    ** 083 EVL 20170526          Adding unwrapping for DirectManipulation and Droppable interfaces.
    ** 084 ECF 20170822          Added unwrapping for XmlData interface.
    ** 085 OM  20170530          Added support for TIMER FWD extension and ControlFrames.
    ** 087 CA  20170929          Added MNEMONIC and PREPROCESSED-LABEL FWD extension attributes.
    ** 088 GES 20171026          Added EmailSender FWD extension.
    ** 089 SVL 20171030          Added unwrapping to Report.
    ** 090 OM  20171122          Added WriteProtectable interface support for READ-ONLY attribute.
    ** 091 GES 20171206          Changes in ErrorManager make silent error mode support unnecessary.
    ** 092 GES 20171207          Removed explicit bypass on pending error (new silent error mode).
    ** 093 CA  20180313          Added FWD extension SESSION:DISABLE-REDRAW.
    ** 094 EVL 20180423          Renamed Report to FwdReport.
    ** 095 GES 20180419          Implemented the backing support for serialization because it is
    **                           needed for RAW-TRANSFER.
    **     CA  20180501          Added AUTO-RETURN attribute.
    **     CA  20180510          Added PROFILER system handle support.
    ** 096 EVL 20180615          Fix for handling unsupported attributes in silent mode.
    ** 097 CA  20181029          Added CALL resource support and related refactoring.
    ** 098 CA  20181112          Added TRANSACTION resource support.
    ** 099 OM  20181114          Added unwrapping to NamedSerializable.
    ** 100 CA  20181128          Added CLIENT-PRINCIPAl resource support.
    ** 101 HC  20181124          Implemented TREEVIEW widget and related changes.
    ** 102 CA  20181204          Added DEBUGGER handle support.
    **     HC  20181220          Added method unwrapRemoveNode.
    ** 103 HC  20190206          Added very early stage of TABSET widget implementation only
    **                           providing public interface and to allow conversion of legacy code.
    **                           Fixed an NPE condition during construction of unknown frame handle.
    **     EVL 20190214          Small javadoc fix for TABSET related method.
    **     CA  20190309          Added HTML-BROWSER support.
    **     HC  20190313          Initial implementation of TREELIST widget. TREEVIEW widget
    **                           refactored to make it the base for the TREELIST widget.
    ** 104 OM  20190325          Added unwrapping to Rejectable, DataSet, JsonData,
    **                           DataRelation, DataSource and other interfaces.
    **                           Removed duplicate of invalidAttribute().
    ** 105 CA  20190423          Basic implementation of STREAM-HANDLE (untested).
    ** 106 IAS 20190501          Added SECURITY-POLICY support.
    **         20190506          Added AUDIT-POLICY, AUDIT-CONTROL support.
    **     OM  20190508          Switched to FWD proxy factory implementation for generation of
    **                           invalidAttrAccessProxy.
    ** 107 OM  20190513          Added unwrapping to EmptyTempTable.
    ** 108 HC  20190614          Added unwrapping to CustomFont.
    ** 109 IAS 20190617          Added invalidAttribute(String attr, handle h, int errNum) method.
    ** 110 OM  20190611          Added unwrapping to new interfaces: DataSetChangeable and CreateLike.
    **                           Added chained-attribute expression error.
    ** 111 OM  20190717          Added isType() method for checking the type of the resource.
    **     CA  20190720          Fixed unknown value returned by 'dereference', in a chain call.
    **     CA  20190812          Always save the current runtime resource from an assigned mutable
    **                           resource.
    **     HC  20190826          Added logical -> handle conversion for the cases when logical value is
    **                           assigned to a handle output argument.
    ** 112 OM  20190909          Added ErrorString interface.
    ** 113 EVL 20191123          Added PaneEntity unwrap method.
    **     HC  20191126          Implemented RESIZE attribute for DIALOG-BOX. This is an extension to
    **                           4GL.
    ** 114 HC  20190614          Initial implementation of IMAGELIST widget.
    **                           assigned to a handle output argument.
    ** 115 MAG 20190920          Added PROGRESS-BAR support.
    ** 116 SBI 20200225          Added Calendar widget support.
    ** 117 MAG 20200115          Implement OLE Drag&Drop.
    ** 118 IAS 20200221          Added Available interface.
    **     CA  20200303          Removed duplicated methods after rebase.
    **     CA  20200304          Added support for unwrapImageOnly, unwrapSignature.
    **                           Allow 4GL code access to the handle's resource.
    **                           invalidAttrAccessProxy can't be used from conversion, so its
    **                           initialization is protected.
    **     RFB 20200303          Added BUTTON-LIST widget support.
    **     RFB 20200304          Added additional ButtonList class support.
    ** 119 GES 20200221          Added TitledElement.
    ** 120 CA  20200330          'invalidAttribute' must suffix the error message with the error number,
    **                           if the handle is unknown.
    **     SBI 20200414          Added unwrapWithCaption().
    **     CA  20200427          Added unwrapRequestResponseInfo().
    **     SBI 20200520          Added unwrapListImages().
    ** 121 VVT 20200805          Comhandle input procedure parameters can now be converted to handles.
    **                           See #4841 and #4831 issues.
    ** 122 GES 20200627          Renamed Coordinates interface to be more generic.
    **     HC  20200726          Initial implementation of SPREADSHEET widget and related changes.
    **     VVT 20200805          Comhandle input procedure parameters can now be converted to handles.
    **                           See #4841 and #4831 issues.
    ** 123 AIL 20200826          Added DummyResource used for representing invalid resources with fixed id.
    ** 124 IAS 20200908          Rework (de)serialization.
    ** 125 IAS 20201007          Added Type enum
    **     SVL 20201221          Added unwrapMinHeightChars.
    **     OM  20201030          Invalid attribute API support for getters/setters.
    **     OM  20201118          Extracted SERIALIZE-HIDDEN into independent interface.
    **     OM  20201203          Fixed handling of READ/ONLY attributes.
    ** 126 ME  20210128          Throw instead of force display error for invalid handle access.
    **     CA  20210306          HANDLE function can not retrieve a object resource (ERROR condition is raised).
    **                           Moved to always incremental resource IDs.
    **     CA  20210310          Small performance improvement in removeResource.
    **     ME  20210504          Added isIncompatibleTypesOnConversion override for invalid POLY
    **                           conversion. Support int64, decimal and date assign.
    **     AIL 20210615          Added a flag to detect if the handle should be set after run ... persistent set.
    **     VVT 20210628          Using generics in the TREELIST/TREEVIEW implementation eliminated.
    **     VVT 20210909          unwrapDataObject() method added. See #5172-73.
    ** 127 HC  20211201          Implemented TREEVIEW:CHECK-BOXES attribute.
    **     AL2 20220319          Added value proxy check in assign.
    **     VVT 20220720          POJOComObject can now be used to set handle value.
    **     VVT 20221003          CommonHandle.getResourceType() method renamed to resourceType() to prevent conflicts
    **                           with namesakes in DMO. See #6694.
    **     TJD 20220504          Java 11 compatibility minor changes
    **     CA  20220426          Added unwrapPrimary, for PRIMARY attribute.
    **     CA  20220428          Added unwrapWebContext, for WEB-CONTEXT resource.
    **     CA  20220516          Added unwrapCompiler, for COMPILER resource.
    **     OM  20220609          Added unwrappers for new interfaces.
    **     VVT 20220913          CommonHandle.getResourceType() method renamed to resourceType() to prevent conflicts
    **                           with namesakes in DMO. See #6694.
    **     CA  20230110          Added a Helper class to provide direct access to context-local APIs.
    ** 128 CA  20230215          'instantiateDefault' now is implemented by each sub-class.  Added unknown.UNKNOWN
    **                           singleton (used by FWD runtime at this time).
    **     CA  20230215          'duplicate()' method returns the real type instead of BDT.
    **     CA  20230215          Performance fix for handle.set - avoid calling 'checkUndoable' (which will
    **                           trigger lambda creation) if the instance is not undoable.
    ** 129 GBB 20230323          A new method unwrapDsLogManager added.
    ** 130 GBB 20230512          Logging methods replaced by CentralLogger/ConversionStatus.
    ** 131 RAA 20230525          Creating a new BaseDataType instance is now done using BaseDataTypeFactory.
    ** 132 CA  20230712          Do not resolve the 'invalidAttrAccessProxy' in the static c'tor, if this is
    **                           executed during conversion.
    ** 133 GBB 20230719          Fix for SESSION-ID, unwrapCommonSessionId added.
    ** 134 CA  20240324          Use logical constants for TRUE, FALSE, UNKNOWN, within internal FWD runtime.
    ** 135 EVL 20240529          Fix for unwanted EROOR for invalid attribute getter.  We need to use WARNING
    **                           instead because this considers SUPPRESS-WARNINGS session flag value.
    ** 136 ES  20250321          Added unwrapAsyncRequestAttributes method, for FIRST-ASYNC-REQUEST and
    **                           LAST-ASYNC-REQUEST attributes.
    ** 137 AL2 20250530          Added getIndependentFromContext.
    */

    /*
    ** This program is free software: you can redistribute it and/or modify
    ** it under the terms of the GNU Affero General Public License as
    ** published by the Free Software Foundation, either version 3 of the
    ** License, or (at your option) any later version.
    **
    ** This program is distributed in the hope that it will be useful,
    ** but WITHOUT ANY WARRANTY; without even the implied warranty of
    ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    ** GNU Affero General Public License for more details.
    **
    ** You may find a copy of the GNU Affero GPL version 3 at the following
    ** location: https://www.gnu.org/licenses/agpl-3.0.en.html
    **
    ** Additional terms under GNU Affero GPL version 3 section 7:
    **
    **   Under Section 7 of the GNU Affero GPL version 3, the following additional
    **   terms apply to the works covered under the License.  These additional terms
    **   are non-permissive additional terms allowed under Section 7 of the GNU
    **   Affero GPL version 3 and may not be removed by you.
    **
    **   0. Attribution Requirement.
    **
    **     You must preserve all legal notices or author attributions in the covered
    **     work or Appropriate Legal Notices displayed by works containing the covered
    **     work.  You may not remove from the covered work any author or developer
    **     credit already included within the covered work.
    **
    **   1. No License To Use Trademarks.
    **
    **     This license does not grant any license or rights to use the trademarks
    **     Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks
    **     of Golden Code Development Corporation. You are not authorized to use the
    **     name Golden Code, FWD, or the names of any author or contributor, for
    **     publicity purposes without written authorization.
    **
    **   2. No Misrepresentation of Affiliation.
    **
    **     You may not represent yourself as Golden Code Development Corporation or FWD.
    **
    **     You may not represent yourself for publicity purposes as associated with
    **     Golden Code Development Corporation, FWD, or any author or contributor to
    **     the covered work, without written authorization.
    **
    **   3. No Misrepresentation of Source or Origin.
    **
    **     You may not represent the covered work as solely your work.  All modified
    **     versions of the covered work must be marked in a reasonable way to make it
    **     clear that the modified work is not originating from Golden Code Development
    **     Corporation or FWD.  All modified versions must contain the notices of
    **     attribution required in this license.
    */

    package com.goldencode.p2j.util;

    import static com.goldencode.util.NativeTypeSerializer.*;
    import java.io.*;
    import java.lang.reflect.*;
    import java.util.*;
    import java.util.logging.*;

    import com.goldencode.p2j.extension.*;
    import com.goldencode.p2j.cfg.*;
    import com.goldencode.p2j.comauto.*;
    import com.goldencode.p2j.email.*;
    import com.goldencode.p2j.persist.*;
    import com.goldencode.p2j.reporting.*;
    import com.goldencode.p2j.security.*;
    import com.goldencode.p2j.ui.*;
    /* Calendar must be imported explicitly */
    import com.goldencode.p2j.ui.Calendar;
    import com.goldencode.p2j.ui.ocx.*;
    import com.goldencode.p2j.util.logging.*;
    import com.goldencode.p2j.xml.*;
    import com.goldencode.proxy.*;

    /**
     * A class that represents a Progress 4GL compatible handle data type. This
     * is a container for an object of type {@link WrappedResource}.  Such
     * objects can be passed around as a regular {@link BaseDataType} wrapper
     * but the backing object can be indirectly accessed via the {@link #get}
     * method.
     * <p>
     * The following is the mapping of Progress language features to the
     * corresponding feature in this class:
     * <p>
     * <pre>
     * string        function (default format)      {@link #toString()}
     *                        (user-defined format) {@link #toString(String)}
     *                        (export format)       {@link #toStringExport()}
     * valid-handle  function                       {@link #isValid}
     * widget-handle function                       {@link #fromString}
     * </pre>
     * <p>
     * There are 2 deviations between this class and its behavior in the Progress
     * 4GL:
     * <p>
     * <ol>
     *    <li> The default format string is larger in Java than in Progress since
     *         the Java implementation uses all possible 32-bit values as its
     *         handle identifiers. This could be made compatible by limiting the
     *         possible values used to those that would fit into the Progress
     *         equivalent. This would probably require that every handle be
     *         registered or assigned a unique value at construction.
     *    <li> In Progress, it is possible that one could create a loop to
     *         instantiate all possible handles using the WIDGET-HANDLE function.
     *         This means that one might not have used the STRING function to get
     *         the text representation since that loop could create strings for
     *         all integers in the possible range of handle identifiers. This
     *         seems like a bad practice, but if it is ever used in reality, it
     *         would invalidate the implementation of {@link #fromString} which
     *         depends upon a map maintained during {@link #toString}.  The
     *         solution is the same as for the oversized text representation
     *         problem above (a registry created at construction of every
     *         handle).
     * </ol>
     */
    public class handle
    extends BaseDataType
    {
       /** Logger */
       private static final CentralLogger LOG = CentralLogger.get(handle.class.getName());

       /** Stores context-local state variables. */
       private static final ContextLocal<WorkArea> work =
       new ContextLocal<WorkArea>()
       {
          @Override
          public WeightFactor getWeight()
          {
             return WeightFactor.LAST;
          };

          protected synchronized WorkArea initialValue()
          {
             return new WorkArea();
          }
       };

       /**
        * Dynamic proxy returned by unwrap APIs when the handle is invalid or not
        * of the expected type.  Gets populated on class load.
        */
       private static HandleCommon invalidAttrAccessProxy = null;

       /** Stores the referenced data of this handle. */
       private WrappedResource value = null;

       /**
        * Flags a possible intermediary handle used in a chained construction (like a:b:c).
        * In this case the error is different (10068 instead of 3135/3140).
        */
       private boolean possibleChained = true;

       /**
        * A marker for the unknown value of the argument of {@code readOnlyError()}. The semantic of it is that
        * the value was not passed from ABL code, not that it is ABL {@code ?} value.
        */
       public static final Object UNKNOWN_ARGUMENT = new Object();

       static
       {
          if (!Configuration.isRuntimeConfig())
          {
             invalidAttrAccessProxy = null;
          }
          else
          {
             try
             {
                invalidAttrAccessProxy = ProxyFactory.getProxy(InvalidAttributeAccess.class,
                                                               new Class<?>[] { HandleCommon.class },
                                                               false, null);
             }
             catch (Throwable t)
             {
                LOG.severe("Can not initialize handle's invalid access proxy:" + t);
             }
          }
       }

       /**
        * Default constructor, creates an instance that represents the unknown value.
        */
       public handle()
       {
       }

       /**
        * Default constructor, creates an instance that represents the unknown value.
        * @param possibleChained
        *        Flags a possible intermediary handle used in a chained construction
        */
       public handle(boolean possibleChained)
       {
          this.possibleChained = possibleChained;
       }

       /**
        * This is a special c'tor which should be used only when converting the
        * value returned by a function or method with polymorphic return type into the
        * expected type (i.e. DYNAMIC-FUNCTION()).  In such cases, the 4GL does some
        * automatic type conversion (see {@link #assign(BaseDataType)}).
        *
        * @param    value
        *           The value to be used for this instance.
        */
       public handle(BaseDataType value)
       {
          if (value == null || value.isUnknown())
          {
             setUnknown();
          }
          else
          {
             assign(value);
          }
       }

       /**
        * Constructor used to create values from {@code initial} value. For this datatype, there are
        * no options, only the {@code ?} (unknown) value is actually expected.
        *
        * @param   initVal
        *          Ignored. Always create an unknown {@code handle}.
        */
       public handle(String initVal)
       {
          setUnknown();
       }

       /**
        * Constructs an instance that has the contained object reference and
        * <code>unknown value</code> that exactly matches that of the passed-in
        * instance.
        *
        * @param    value
        *           The instance to pattern from.
        */
       public handle(handle value)
       {
          assign(value);
       }

       /**
        * Constructs an instance that has the contained object reference.
        *
        * @param    value
        *           The instance to pattern from.
        */
       public handle(WrappedResource value)
       {
          assign(value);
       }

       /**
        * Constructs an instance that has the contained object reference.
        *
        * @param    stream
        *           The instance to pattern from.
        */
       public handle(Stream stream)
       {
          assign(new TransparentWrapper(stream));
       }

       /**
        * Constructs an instance that has the contained object reference.
        *
        * @param    value
        *           The frame instance.
        */
       public handle(CommonFrame value)
       {
          // the null check was added to prevent NPE for the following expression:
          // "h.unwrapWidget().getFrameHandle().isValid()". in this case it is desired to get unknown frame
          // to prevent the NPE
          if (value != null)
          {
             assign(value.asWidgetHandle());
          }
       }

       /**
        * Get the type
        * @return type
        */
       public Type getType()
       {
          return Type.HANDLE;
       }

       /**
        * Get an instance of {@link Helper}, which has the context-local instance saved, so API access can be done
        * without a context-local query.
        *
        * @return   See above.
        */
       public static Helper getHelper()
       {
          return new Helper(work.get());
       }

       /**
        * Check the type of resource in the handle. Return {@code true} if and only if handle
        * is valid and contains resource of specific type.
        *
        * @param    handleToCheck
        *           The handle instance to check.
        * @param    clazz
        *           Specific class type which will be compare.
        *
        * @return   {@code true} if handleToCheck contains resource an instance of clazz,
        *           {@code false} otherwise.
        */
       public static boolean isHandleTypeOf(handle handleToCheck, Class<?> clazz)
       {
          if (handleToCheck == null || !handleToCheck._isValid() || handleToCheck.isUnknown())
          {
             return false;
          }
          WrappedResource resource = handleToCheck.getResource();

          return clazz.isInstance(resource);
       }

       /**
        * Get the underlying resource for this handle.
        *
        * @param    h
        *           The handle resource.
        *
        * @return   The {@link WrappedResource} instance.  If the handle is not valid, throw a ERROR
        *           condition.
        */
       public static WrappedResource getResource(handle h)
       {
          if (!h._isValid())
          {
             ErrorManager.recordOrThrowError(3135,
                                             "Invalid handle.  Not initialized or points to a " +
                                             "deleted object", false, true);
             return null;
          }
          return h.getResource();
       }

       /**
        * Emitted and to be used only in cases the attribute is read-only. It displays appropriate error message.
        *
        * @param    h
        *           The handle used to access the attribute.
        * @param    attribute
        *           The read-only attribute.
        */
       public static void readOnlyError(handle h, String attribute)
       {
          readOnlyError(h, attribute, UNKNOWN_ARGUMENT);
       }

       /**
        * Emitted and to be used only in cases the attribute is read-only. It displays appropriate error message.
        *
        * @param    h
        *           The handle used to access the attribute.
        * @param    attribute
        *           The read-only attribute.
        * @param    expr
        *           The value which is attempted to be assigned to the read-only attribute.
        */
       public static void readOnlyError(handle h, String attribute, Object expr)
       {
          if (attribute == null)
          {
             throw new IllegalArgumentException("The attribute is null !");
          }

          CommonHandle unwrapped = unwrapImpl(h, CommonHandle.class);
          String type = unwrapped.resourceType().toStringMessage();
          String uppercaseAttr = attribute.toUpperCase();

          if (expr == null || (expr instanceof BaseDataType && ((BaseDataType) expr).isUnknown()))
          {
             switch (uppercaseAttr)
             {
                // This is a list of attributes that accept unknown as value OR first check whether the attribute
                // is writable. In these cases we must NOT raise error 4083.
                // TODO: improve the list. If needed (too many attributes) we may need reverse the check, Ie
                //       filter the non-unknown attributes
                case "HANDLE":
                case "NEXT-SIBLING":
                   break;
                default:
                   ErrorManager.recordOrShowError(4083, uppercaseAttr, type + " widget");
                   // **Unable to assign UNKNOWN value to attribute <attribute> on <widget id>.
                   return;
             }
          }

          // standard "**<attribute-name> is not a <access-mode> attribute for <object-type>" message
          invalidAttribute(uppercaseAttr, true, type);
       }

       /**
        * Convert the string representation of a handle into the original handle
        * instance. This facility can only work for handles that have been
        * converted at least once into a string via {@link #toString}. Such
        * handles are stored in a map for conversion purposes.
        *
        * @param    txt
        *           A valid text representation of a handle.
        * @return   a <code>handle</code> instance
        */
       public static handle fromString(character txt)
       {
          return fromString(txt.toStringMessage());
       }

       /**
        * Convert the string representation of a handle into the original handle
        * instance. This facility can only work for handles that have been
        * converted at least once into a string via {@link #toString}. Such
        * handles are stored in a map for conversion purposes.
        *
        * @param    txt
        *           A valid text representation of a handle.
        * @return   a <code>handle</code> instance
        */
       public static handle fromString(String txt)
       {
          return fromString(txt, true);
       }

       /**
        * Convert the string representation of a handle into the original handle
        * instance. This facility can only work for handles that have been
        * converted at least once into a string via {@link #toString}. Such
        * handles are stored in a map for conversion purposes.
        *
        * @param    txt
        *           A valid text representation of a handle.
        * @param    defaultZero
        *           A flag indicating if the handle returned is the zero handle in case there is
        *           no resource with the specified id.
        *
        * @return   a <code>handle</code> instance
        */
       public static handle fromString(String txt, boolean defaultZero)
       {

          Long id = ResourceIdHelper.idFromString(txt);
          if (ResourceIdHelper.isUnknown(id))
          {
             return new handle();
          }
          else if (ResourceIdHelper.isZero(id))
          {
             return new handle(ZERO_RESOURCE);
          }

          return fromResourceId(id, defaultZero, true);
       }

       /**
        * Converts the number representation of a handle into the original handle instance.
        * <p>
        * For handles <em>whose backing resources still exist</em> and which have been cached by
        * their IDs via {@link #resourceId(WrappedResource)} (which is called at various points in
        * the handle's life cycle), the method returns a valid handle instance. For handles whose
        * backing resources no longer exist, or which have never had their backing resources cached,
        * the method returns a zero handle, i.e. handle with "0" string representation.
        *
        * @param   resourceId
        *          Resource identifier.
        * @return   a <code>handle</code> instance
        */
       public static handle fromResourceId(Long resourceId)
       {
          return fromResourceId(resourceId, true);
       }

       /**
        * Converts the number representation of a handle into the original handle instance.
        * <p>
        * For handles <em>whose backing resources still exist</em> and which have been cached by
        * their IDs via {@link #resourceId(WrappedResource)} (which is called at various points in
        * the handle's life cycle), the method returns a valid handle instance. For handles whose
        * backing resources no longer exist, or which have never had their backing resources cached,
        * the method returns a zero handle, i.e. handle with "0" string representation, or a
        * dummy handle - an invalid handle with a specified string representation.
        *
        * @param   resourceId
        *          Resource identifier.
        * @param   defaultZero
        *          A flag indicating if the handle returned is the zero handle in case there is
        *          no resource with the specified id.
        *
        * @return   a <code>handle</code> instance
        */
       public static handle fromResourceId(Long resourceId, boolean defaultZero)
       {
          return fromResourceId(resourceId, defaultZero, false);
       }

       /**
        * Converts the number representation of a handle into the original handle instance.
        * <p>
        * For handles <em>whose backing resources still exist</em> and which have been cached by
        * their IDs via {@link #resourceId(WrappedResource)} (which is called at various points in
        * the handle's life cycle), the method returns a valid handle instance. For handles whose
        * backing resources no longer exist, or which have never had their backing resources cached,
        * the method returns a zero handle, i.e. handle with "0" string representation, or a
        * dummy handle - an invalid handle with a specified string representation.
        *
        * @param   resourceId
        *          Resource identifier.
        * @param   defaultZero
        *          A flag indicating if the handle returned is the zero handle in case there is
        *          no resource with the specified id.
        * @param   legacyHandleFunct
        *          Flag indicating if this call originates from a HANDLE function call.
        *
        * @return   a <code>handle</code> instance
        */
       public static handle fromResourceId(Long resourceId, boolean defaultZero, boolean legacyHandleFunct)
       {
          WorkArea wa = work.get();
          WrappedResource resource = wa.idResources.get(resourceId);

          if (resource != null)
          {
             if (legacyHandleFunct && resource instanceof ObjectResource)
             {
                ErrorManager.recordOrThrowError(13443,
                                                "Cannot pass an object reference to the WIDGET-HANDLE function",
                                                false);
                return new handle();
             }
             else
             {
                return new handle(resource);
             }
          }

          if (defaultZero)
          {
             return new handle(ZERO_RESOURCE);
          }
          else
          {
             return new handle(new DummyResource(resourceId));
          }
       }

       /**
        * This API should be called only in case of a attribute/method access using a resource which does not
        * support it.  It shows appropriate error messages, depending on handle state and attribute/method.
        * <p>
        * This must not be called in cases of a not-supported attribute invoked as a lvalue (i.e. a setter for a
        * not-supported attribute is invoked). In this case, call {@link #readOnlyError}.
        *
        * @param    attr
        *           The attribute/method name which is not supported by the handle.
        * @param    h
        *           The handle used to access the attribute/method.
        * @param    setterMode
        *           The access mode. Use {@code true} for setter and {@code false} for getter/query.
        */
       public static void invalidAttribute(String attr, handle h, boolean setterMode)
       {
          if (!h._isValid())
          {
             // TODO: there are some cases (like FOCUS:attr or SELF:attr access, when FOCUS/SELF
             // are unknown) which show only the 3140 error. this requires conversion changes, as
             // this is something related to the fact that the attr/method access is done directly
             // via a sys-handle, and not via an intermediate variable.

             String msg1 = "Invalid handle.  Not initialized or points to a deleted object";
             int code1 = 3135;

             if ("dereference".equals(attr))
             {
                ErrorManager.displayError(code1, msg1, false);
             }
             else
             {
                // special cases, depending on which method is executed
                String msg2 = "Cannot access the " + attr + " attribute because the widget does not exist";

                int[] errIds = { code1, 3140 };
                String[] msgs = { msg1, msg2 };
                ErrorManager.recordOrThrowError(errIds, msgs, false, false);
             }
          }
          else
          {
             // valid handle, wrong API, show error
             invalidAttribute(attr, setterMode, h.unwrapType().resourceType().toStringMessage());
          }
       }

       /**
        * This API should be called only in case of a attribute/method access using a resource which does not
        * support it.  It shows error messages #4052 with the configured message string.
        *
        * @param    attr
        *           The attribute/method name which is not supported by the handle.
        * @param    setter
        *           The access mode. Use {@code true} for setter and {@code false} for getter/query.
        * @param    type
        *           The type of the widget used to access the invalid attribute/method.
        */
       public static void invalidAttribute(String attr, boolean setter, String type)
       {
          // NOTE: the single-t "setable" is intentional to match P4GL
          invalidAttribute(attr, setter ? "setable" : "queryable", type, "widget");
       }

       /**
        * This API should be called only in case of a attribute/method access using a resource which does not
        * support it.  It shows error messages #4052 with the configured message string.
        *
        * @param    attr
        *           The attribute/method name which is not supported by the handle.
        * @param    accessMode
        *           The access mode. Use {@code true} for setter and {@code false} for getter/query.
        * @param    subtype
        *           The subtype of the widget used to access the invalid attribute/method.
        * @param    type
        *           The type of the widget used to access the invalid attribute/method.
        */
       public static void invalidAttribute(String attr, String accessMode, String subtype, String type)
       {
          StringBuilder sb = new StringBuilder();
          sb.append(attr);
          sb.append(" is not a ");
          sb.append(accessMode);
          sb.append(" attribute for ");
          if (subtype != null && !subtype.isEmpty())
          {
             sb.append(subtype);
             sb.append(" ");
          }
          sb.append(type);
          ErrorManager.displayWarning(4052, sb.toString());
          // **<attribute> is not a <settable/queryable> attribute for <widget id>.
       }

       /**
        * Remove the given resource from the context-local map of all resource.
        * <p>
        * This method should be called by all wrapped resources when deleted,
        * that is all resources implementing {@link WrappedResource} interface.
        *
        * @param    resource
        *           A resource instance to be removed.
        */
       public static void removeResource(WrappedResource resource)
       {
          if (resource == null)
          {
             return;
          }

          WorkArea wa = work.get();
          Long id = wa.resourceIds.remove(resource);
          if (id != null)
          {
             wa.idResources.remove(id);
          }
       }

       /**
        * Get the ID of the given resource, as used by the {@link #toString} and
        * {@link #fromString} APIs.
        * <p>
        * The method allocates additional resources together with the provided wrapped resource,
        * thus it is necessary that {@link #removeResource(WrappedResource)} is called when
        * the returned resource id is not needed anymore (i.e. the related resource is deleted),
        * see {@link #removeResource(WrappedResource)} for more details.
        *
        * @param    resource
        *           A resource instance.
        *
        * @return   The ID of this resource.
        */
       public static Long resourceId(WrappedResource resource)
       {
          if (resource == ZERO_RESOURCE)
          {
             return 0L;
          }

          Long existingId = resource.id();

          // resource id already set at the resource?
          if (existingId != null)
          {
             return existingId;
          }

          WorkArea wa = work.get();

          // resource id already allocated?
          existingId = wa.resourceIds.get(resource);
          if (existingId != null)
          {
             // yes, save it at the resource, too
             resource.id(existingId);

             return existingId;
          }

          if (!resource.valid())
          {
             if (LOG.isLoggable(Level.FINE))
             {
                LOG.log(Level.FINE,
                        "You are creating a new ID for an invalid resource " +
                        resource.getClass().getName() + "!",
                        new Exception());
             }
             else if (LOG.isLoggable(Level.WARNING))
             {
                LOG.log(Level.WARNING,
                        "You are creating a new ID for an invalid resource " +
                        resource.getClass().getName() + "! (enable FINE logging for a stacktrace)");
             }
          }

          // allocate new resource id - collision with existing ids must be prevented
          Long id = null;
          do
          {
             id = wa.nextId;
             wa.nextId = ResourceIdHelper.getNext(id);
          }
          while (wa.idResources.containsKey(id));

          wa.idResources.put(id, resource);
          wa.resourceIds.put(resource, id);

          // save it at the resource, too
          resource.id(id);

          return id;
       }

       /**
        * Check if the given resource is known (has an associated ID).
        *
        * @param    resource
        *           A resource, valid or not.
        *
        * @return   {@code true} if the resource has an associated ID.
        */
       static boolean knownResource(WrappedResource resource)
       {
          WorkArea wa = work.get();

          return wa.resourceIds.get(resource) != null;
       }

       /**
        * Build an {@link ExternalResource} instance and associated an ID to it.
        *
        * @return   A handle with a new {@link ExternalResource} instance.
        */
       public static handle buildExternalResource()
       {
          ExternalResource resource = new ExternalResource();
          // allocate an ID immediately
          handle.resourceId(resource);

          return new handle(resource);
       }

       /**
        * Unwrap the given handle so that it returns an instance compatible with
        * the given interface, <code>ifc</code>. If the handle is invalid or is
        * not compatible with the given interface, a dynamic proxy is returned
        * (see {@link #invalidAttrAccessProxy}.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        * To return the wrapped resource for a call site that will not guarantee
        * the attribute/method invocation use {@link #getResource()} instead.
        *
        * @param    h
        *           The handle to be unwrapped.
        * @param    ifc
        *           The expected interface.
        *
        * @return   See above.
        */
       @SuppressWarnings("unchecked")
       private static <T> T unwrapImpl(handle h, Class<T> ifc)
       {
          WrappedResource value = h.value;
          if (h._isValid() && ifc.isAssignableFrom(value.getClass()))
          {
             return (T) value;
          }

          work.get().invalidCalls.push(h);
          return (T) invalidAttrAccessProxy;
       }

       /**
        * Get the legacy attribute or method name mapped by this method.
        *
        * @param    method
        *           The method for which the legacy name is needed.
        * @param    args
        *           The method's arguments.
        *
        * @return   The legacy name from the method annotation or the converted API name, if not
        *           found in the respective annotation.
        */
       private static String getAttrOrMethodName(Method method, Object[] args)
       {
          String name = method.getName();

          if ("readOnlyError".equals(name) &&
              args.length == 1             &&
              args[0] != null              &&
              (args[0] instanceof String)  &&
              method.getDeclaringClass().equals(CommonHandle.class))
          {
             return ((String) args[0]).toUpperCase();
          }

          String api = null;
          LegacyAttribute legacyAttr = method.getAnnotation(LegacyAttribute.class);
          if (legacyAttr != null && !legacyAttr.ignore())
          {
             api = legacyAttr.name();
          }

          LegacyMethod legacyMthd = method.getAnnotation(LegacyMethod.class);
          if (legacyMthd != null)
          {
             api = legacyMthd.name();
          }

          return api == null ? name : api;
       }

       /**
        * Check if this resource is an {@link ExternalResource}.
        *
        * @return   <code>true</code> if this is an {@link ExternalResource} instance.
        */
       public boolean isExternalResource()
       {
          return value instanceof ExternalResource;
       }

       /**
        * Unwrap this handle to a {@link CommonHandleChain} instance. If the
        * handle is not a procedure, widget, window or frame handle or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonHandleChain unwrap()
       {
          return unwrapImpl(this, CommonHandleChain.class);
       }

       /**
        * Unwrap this handle to a {@link CommonHandleTree} instance. If the handle is
        * not a CommonHandleTree handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public CommonHandleTree unwrapTree()
       {
          return unwrapImpl(this, CommonHandleTree.class);
       }

       /**
        * Unwrap this handle to a {@link ADMData} instance. If the handle is
        * not a ADMData handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public ADMData unwrapADMData()
       {
          return unwrapImpl(this, ADMData.class);
       }

       /**
        * Unwrap this handle to a {@link AsyncRequest} instance. If the handle is
        * not a <code>AsynchronousRequest</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public AsyncRequest unwrapAsync()
       {
          return unwrapImpl(this, AsyncRequest.class);
       }

       /**
        * Unwrap this handle to a {@link AsyncRequestCountAttribute} instance. If the handle is
        * not a AsyncRequestCountAttribute handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public AsyncRequestCountAttribute unwrapAsyncRequestCount()
       {
          return unwrapImpl(this, AsyncRequestCountAttribute.class);
       }

       /**
        * Unwrap this handle to a {@link Buffer} instance. If the
        * handle is not the Buffer handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Buffer unwrapBuffer()
       {
          return unwrapImpl(this, Buffer.class);
       }

       /**
        * Unwrap this handle to a {@link BufferCollection} instance. If the handle is not the
        * {@code BufferCollection} handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public BufferCollection unwrapBufferCollection()
       {
          return unwrapImpl(this, BufferCollection.class);
       }

       /**
        * Unwrap this handle to a {@link BufferField} instance. If the
        * handle is not the BufferField handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public BufferField unwrapBufferField()
       {
          return unwrapImpl(this, BufferField.class);
       }

       /**
        * Unwrap this handle to a {@link CallResource} instance. If the
        * handle is not the Call handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CallResource unwrapCall()
       {
          return unwrapImpl(this, CallResource.class);
       }

       /**
        * Unwrap this handle to a {@link Checkable} instance. If the
        * handle is not the Checkable handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Checkable unwrapCheckable()
       {
          return unwrapImpl(this, Checkable.class);
       }

       /**
        * Unwrap this handle to a {@link ClientPrincipalResource} instance. If the
        * handle is not the ClientPrincipal handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public ClientPrincipalResource unwrapClientPrincipal()
       {
          return unwrapImpl(this, ClientPrincipalResource.class);
       }

       /**
        * Unwrap this handle to a {@link Clearable} instance. If the
        * handle is not the Clearable handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Clearable unwrapClearable()
       {
          return unwrapImpl(this, Clearable.class);
       }

       /**
        * Unwrap this handle to a {@link Clipboard} instance. If the handle is not a Clipboard handle
        * or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public Clipboard unwrapClipboard()
       {
          return unwrapImpl(this, Clipboard.class);
       }

       /**
        * Unwrap this handle to a {@link ColorTableResource} instance. If the handle is
        * not a ColorTableResource handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public ColorTableResource unwrapColorTable()
       {
          return unwrapImpl(this, ColorTableResource.class);
       }

       /**
        * Unwrap this handle to a {@link Compiler} instance. If the
        * handle is not a <code>RcodeInfo</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Compiler unwrapCompiler()
       {
          return unwrapImpl(this, Compiler.class);
       }

       /**
        * Unwrap this handle to an {@link com.goldencode.p2j.ui.ReplaceInterface} instance. If the
        * handle is not an <code>EditorInterface</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state
        * of the last used handle.
        *
        * @return   See above.
        */
       public ReplaceInterface unwrapReplace()
       {
          return unwrapImpl(this, ReplaceInterface.class);
       }

       /**
        * Unwrap this handle to an {@link com.goldencode.p2j.ui.EditorInterface} instance. If the
        * handle is not an <code>EditorInterface</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state
        * of the last used handle.
        *
        * @return   See above.
        */
       public EditorInterface unwrapEditor()
       {
          return unwrapImpl(this, EditorInterface.class);
       }

       /**
        * Unwrap this handle to a {@link com.goldencode.p2j.ui.BrowseInterface} instance. If the
        * handle is not the <code>BrowseInterface</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public BrowseInterface unwrapBrowse()
       {
          return unwrapImpl(this, BrowseInterface.class);
       }

       /**
        * Unwrap this handle to a {@link com.goldencode.p2j.ui.Labels} instance. If the
        * handle is not the <code>Labels</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Labels unwrapLabels()
       {
          return unwrapImpl(this, Labels.class);
       }

       /**
        * Unwrap this handle to an {@link com.goldencode.p2j.ui.FieldGroupInterface} instance.
        *
        * @return   The field group interface instance.
        */
       public FieldGroupInterface unwrapFieldGroup()
       {
          return unwrapImpl(this, FieldGroupInterface.class);
       }

       /**
        * Unwrap this handle to an {@link com.goldencode.p2j.ui.FrameInterface} instance. If the
        * handle is not an <code>FrameInterface</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state
        * of the last used handle.
        *
        * @return   See above.
        */
       public FrameInterface unwrapFrame()
       {
          return unwrapImpl(this, FrameInterface.class);
       }

       /**
        * Unwrap this handle to an {@link com.goldencode.p2j.ui.TopOnlyInterface} instance. If the
        * handle is not an <code>FrameInterface</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state
        * of the last used handle.
        *
        * @return   See above.
        */
       public TopOnlyInterface unwrapTopOnly()
       {
          return unwrapImpl(this, TopOnlyInterface.class);
       }

       /**
        * Unwrap this handle to a {@link AutoReturnElement} instance. If the
        * handle is not the AutoReturnElement handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public AutoReturnElement unwrapAutoReturnElement()
       {
          return unwrapImpl(this, AutoReturnElement.class);
       }

       /**
        * Unwrap this handle to a {@link AutoZapElement} instance. If the
        * handle is not the AutoZapElement handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public AutoZapElement unwrapAutoZapElement()
       {
          return unwrapImpl(this, AutoZapElement.class);
       }

       /**
        * Unwrap this handle to a {@link Available} instance. If the
        * handle is not the Available handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Available unwrapAvailable()
       {
          return unwrapImpl(this, Available.class);
       }

       /**
        * Unwrap this handle to a {@link ScrollbarHorizontalElement} instance. If the
        * handle is not the <code>ScrollbarHorizontalElement</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public ScrollbarHorizontalElement unwrapScrollbarHorizontalElement()
       {
          return unwrapImpl(this, ScrollbarHorizontalElement.class);
       }

       /**
        * Unwrap this handle to a {@link ScrollbarVerticalElement} instance. If the
        * handle is not the ScrollbarVerticalElement handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public ScrollbarVerticalElement unwrapScrollbarVerticalElement()
       {
          return unwrapImpl(this, ScrollbarVerticalElement.class);
       }

       /**
        * Unwrap this handle to a {@link BrowseColumnInterface} instance. If the
        * handle is not the BrowseColumnInterface handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public BrowseColumnInterface unwrapBrowseColumn()
       {
          return unwrapImpl(this, BrowseColumnInterface.class);
       }

       /**
        * Unwrap this handle to a {@link BrowseElement} instance. If the
        * handle is not the BrowseElement handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public BrowseElement unwrapBrowseElement()
       {
          return unwrapImpl(this, BrowseElement.class);
       }

       /**
        * Unwrap this handle to a {@link TitledElement} instance. If the
        * handle is not the TitledElement handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public TitledElement unwrapTitledElement()
       {
          return unwrapImpl(this, TitledElement.class);
       }

       /**
        * Unwrap this handle to a {@link InnerLines} instance. If the
        * handle is not the <code>InnerLines</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public InnerLines unwrapInnerLines()
       {
          return unwrapImpl(this, InnerLines.class);
       }

       /**
        * Unwrap this handle to a {@link MaxCharsElement} instance. If the
        * handle is not the MaxCharsElement handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public MaxCharsElement unwrapMaxCharsElement()
       {
          return unwrapImpl(this, MaxCharsElement.class);
       }

       /**
        * Unwrap this handle to a {@link SortedElement} instance. If the
        * handle is not the SortedElement handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public SortedElement unwrapSortedElement()
       {
          return unwrapImpl(this, SortedElement.class);
       }

       /**
        * Unwrap this handle to a {@link CommonProcedure} instance. If the
        * handle is not a procedure or the SESSION system handle or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonProcedure unwrapCommonProcedure()
       {
          return unwrapImpl(this, CommonProcedure.class);
       }

       /**
        * Unwrap this handle to a {@link CommonField} instance. If the
        * handle is not CommonField resource or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonField unwrapCommonField()
       {
          return unwrapImpl(this, CommonField.class);
       }

       /**
        * Unwrap this handle to a {@link AsyncRequestAttributes} instance. If the
        * handle is not AsyncRequestAttributes resource or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public AsyncRequestAttributes unwrapAsyncRequestAttributes()
       {
          return unwrapImpl(this, AsyncRequestAttributes.class);
       }

       /**
        * Unwrap this handle to a {@link Connectable} instance. If the
        * handle is not a Connectable handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Connectable unwrapConnectable()
       {
          return unwrapImpl(this, Connectable.class);
       }

       /**
        * Unwrap this handle to a {@link ConnectableServer} instance. If the
        * handle is not a ConnectableServer handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public ConnectableServer unwrapConnectableServer()
       {
          return unwrapImpl(this, ConnectableServer.class);
       }

       /**
        * Unwrap this handle to a {@link DatabaseInfo} instance. If the
        * handle is not a procedure, widget, window or frame handle or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public DatabaseInfo unwrapDatabaseInfo()
       {
          return unwrapImpl(this, DatabaseInfo.class);
       }

       /**
        * Unwrap this handle to a {@link DebuggerResource} instance. If the
        * handle is not a DEBUGGER handle or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public DebuggerResource unwrapDebugger()
       {
          return unwrapImpl(this, DebuggerResource.class);
       }

       /**
        * Unwrap this handle to a {@link Dereferenceable} instance. If the
        * handle is not the Dereferenceable handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation to dereference().  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Dereferenceable unwrapDereferenceable()
       {
          return unwrapImpl(this, Dereferenceable.class);
       }

       /**
        * Unwrap this handle to a {@link DisableRedraw} instance. If the
        * handle is not the DisableRedraw handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation to dereference().  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public DisableRedraw unwrapDisableRedraw()
       {
          return unwrapImpl(this, DisableRedraw.class);
       }

       /**
        * Unwrap this handle to a {@link DynamicResource} instance. If the
        * handle is not the DynamicResource handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation to dereference().  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public DynamicResource unwrapDynamicResource()
       {
          return unwrapImpl(this, DynamicResource.class);
       }

       /**
        * Unwrap this handle to a {@link XmlSchema} instance. If the
        * handle is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Encoding unwrapEncoding()
       {
          return unwrapImpl(this, Encoding.class);
       }

       /**
        * Unwrap this handle to a {@link Errorable} instance. If the
        * handle is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Errorable unwrapError()
       {
          return unwrapImpl(this, Errorable.class);
       }

       /**
        * Unwrap this handle to a {@link ErrorString} instance. If the handle is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation. This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public ErrorString unwrapErrorString()
       {
          return unwrapImpl(this, ErrorString.class);
       }

       /**
        * Unwrap this handle to a {@link CommonErrorStatus} instance. If the
        * handle is not the ERROR-STATUS handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonErrorStatus unwrapErrorStatus()
       {
          return unwrapImpl(this, CommonErrorStatus.class);
       }

       /**
        * Unwrap this handle to a {@link CommonFile} instance. If the
        * handle is not the FILE-INFO or a procedure handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonFile unwrapFile()
       {
          return unwrapImpl(this, CommonFile.class);
       }

       /**
        * Unwrap this handle to a {@link CommonFileInfo} instance. If the
        * handle is not the FILE-INFO handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonFileInfo unwrapFileInfo()
       {
          return unwrapImpl(this, CommonFileInfo.class);
       }

       /**
        * Unwrap this handle to a {@link FirstLastProcedureAttribute} instance. If the handle is
        * not a FirstLastProcedureAttribute handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public FirstLastProcedureAttribute unwrapFirstLastProcedure()
       {
          return unwrapImpl(this, FirstLastProcedureAttribute.class);
       }

       /**
        * Unwrap this handle to a {@link FontTableResource} instance. If the handle is
        * not a FontTableResource handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public FontTableResource unwrapFontTable()
       {
          return unwrapImpl(this, FontTableResource.class);
       }

       /**
        * Unwrap this handle to a {@link InstantiatingProcedure} instance. If the handle is
        * not a FirstLastProcedureAttribute handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public InstantiatingProcedure unwrapInstantiatingProcedure()
       {
          return unwrapImpl(this, InstantiatingProcedure.class);
       }

       /**
        * Unwrap this handle to a {@link Keyable} instance. If the handle is not a
        * FirstLastProcedureAttribute handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public Keyable unwrapKeyable()
       {
          return unwrapImpl(this, Keyable.class);
       }

       /**
        * Unwrap this handle to an {@link com.goldencode.p2j.ui.MenuInterface} instance. If the
        * handle is not an <code>MenuInterface</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state
        * of the last used handle.
        *
        * @return   See above.
        */
       public MenuInterface unwrapMenu()
       {
          return unwrapImpl(this, MenuInterface.class);
       }

       /**
        * Unwrap this handle to an {@link com.goldencode.p2j.ui.MnemonicInterface} instance. If the
        * handle is not an <code>MnemonicInterface</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state
        * of the last used handle.
        *
        * @return   See above.
        */
       public MnemonicInterface unwrapMnemonic()
       {
          return unwrapImpl(this, MnemonicInterface.class);
       }

       /**
        * Unwrap this handle to an {@link com.goldencode.p2j.ui.MenuItemInterface} instance. If the
        * handle is not an <code>MenuItemInterface</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state
        * of the last used handle.
        *
        * @return   See above.
        */
       public MenuItemInterface unwrapMenuItem()
       {
          return unwrapImpl(this, MenuItemInterface.class);
       }

       /**
        * Unwrap this handle to a {@link NumEntries} instance. If the handle is
        * not a NumEntries handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public NumEntries unwrapNumEntries()
       {
          return unwrapImpl(this, NumEntries.class);
       }

       /**
        * Unwrap this handle to a {@link NumItems} instance. If the handle is not a NumItems handle
        * or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public NumItems unwrapNumItems()
       {
          return unwrapImpl(this, NumItems.class);
       }

       /**
        * Unwrap this handle to a {@link ButtonInterface} instance. If the handle is not a
        * ButtonInterface handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public ButtonInterface unwrapButton()
       {
          return unwrapImpl(this, ButtonInterface.class);
       }

       /**
        * Unwrap this handle to a {@link ImageSupport} instance. If the handle is not an ImageSupport
        * handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public ImageSupport unwrapImageSupport()
       {
          return unwrapImpl(this, ImageSupport.class);
       }

       /**
        * Unwrap this handle to a {@link ImageWidgetSupport} instance. If the handle is not an
        * ImageWidgetSupport handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public ImageWidgetSupport unwrapImageWidgetSupport()
       {
          return unwrapImpl(this, ImageWidgetSupport.class);
       }

       /**
        * Unwrap this handle to a {@link ImageOnly} instance. If the handle is not an
        * ImageOnly handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public ImageOnly unwrapImageOnly()
       {
          return unwrapImpl(this, ImageOnly.class);
       }

       /**
        * Unwrap this handle to a {@link IterableResource} instance.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public IterableResource unwrapIterableResource()
       {
          return unwrapImpl(this, IterableResource.class);
       }

       /**
        * Unwrap this handle to a {@link IndexedInterface} instance.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public IndexedInterface unwrapIndexed()
       {
          return unwrapImpl(this, IndexedInterface.class);
       }

       /**
        * Unwrap this handle to a {@link SelectionListInterface} instance. If the handle is not a
        * ButtonInterface handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public SelectionListInterface unwrapSelectionList()
       {
          return unwrapImpl(this, SelectionListInterface.class);
       }

       /**
        * Unwrap this handle to a {@link Openable} instance. If the handle is not a
        * Openable handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public Openable unwrapOpenable()
       {
          return unwrapImpl(this, Openable.class);
       }

       /**
        * Unwrap this handle to a {@link OrientationInterface} instance. If the handle is not a
        * OrientationInterface handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public OrientationInterface unwrapOrientation()
       {
          return unwrapImpl(this, OrientationInterface.class);
       }

       /**
        * Unwrap this handle to the com data interface.
        *
        * @return   The com data interface
        */
       public ComData unwrapComData()
       {
          return unwrapImpl(this, ComData.class);
       }

       /**
        * Unwrap this handle to a {@link SliderInterface} instance. If the handle is not a
        * ButtonInterface handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public SliderInterface unwrapSlider()
       {
          return unwrapImpl(this, SliderInterface.class);
       }

       /**
        * Unwrap this handle to a {@link CommonLastEvent} instance. If the
        * handle is not the KEY-READER handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonLastEvent unwrapLastEvent()
       {
          return unwrapImpl(this, CommonLastEvent.class);
       }

       /**
        * Unwrap this handle to ListImages.
        *
        * @return   The ListImages instance.
        */
       public ListImages unwrapListImages()
       {
          return unwrapImpl(this, ListImages.class);
       }

       /**
        * Unwrap this handle to a {@link LegacyLogManager} instance. If the
        * handle is not the LOG-MANAGER handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public LegacyLogManager unwrapLogManager()
       {
          return unwrapImpl(this, LegacyLogManager.class);
       }

       /**
        * Unwrap this handle to a {@link LegacyDsLogManager} instance. If the
        * handle is not the DSLOG-MANAGER handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public LegacyDsLogManager unwrapDsLogManager()
       {
          return unwrapImpl(this, LegacyDsLogManager.class);
       }

       /**
        * Unwrap this handle to a {@link LocalName} instance. If the handle is
        * not a LocalName handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public LocalName unwrapLocalName()
       {
          return unwrapImpl(this, LocalName.class);
       }

       /**
        * Unwrap this handle to a {@link NamedSerializable} instance. If the handle is
        * not a NamedSerializable handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public NamedSerializable unwrapNamedSerializable()
       {
          return unwrapImpl(this, NamedSerializable.class);
       }

       /**
        * Unwrap this handle to a {@link NamespaceURI} instance. If the handle is not a
        * NamedSerializable handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public NamespaceURI unwrapNamespaceURI()
       {
          return unwrapImpl(this, NamespaceURI.class);
       }

       /**
        * Unwrap this handle to a {@link CommonPane} instance. If
        * the handle is not a procedure handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonPane unwrapPane()
       {
          return unwrapImpl(this, CommonPane.class);
       }

       /**
        * Unwrap this handle to a {@link PaneEntity} instance. If the handle is not
        * {@link PaneEntity} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public PaneEntity<?> unwrapPaneEntity()
       {
          return unwrapImpl(this, PaneEntity.class);
       }

       /**
        * Unwrap this handle to a {@link PasswordFieldInterface} instance. If
        * the handle is not a procedure handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public PasswordFieldInterface unwrapPasswordField()
       {
          return unwrapImpl(this, PasswordFieldInterface.class);
       }

       /**
        * Unwrap this handle to a {@link PersistableProcedure} instance. If
        * the handle is not a persistable procedure handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public PersistableProcedure unwrapPersistableProcedure()
       {
          return unwrapImpl(this, PersistableProcedure.class);
       }

       /**
        * Unwrap this handle to a {@link PersistentProcedure} instance. If
        * the handle is not a procedure handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public PersistentProcedure unwrapProcedure()
       {
          return unwrapImpl(this, PersistentProcedure.class);
       }

       /**
        * Unwrap this handle to a {@link CallbackProcedure} instance. If the handle is not a procedure
        * handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public CallbackProcedure unwrapCallbackProcedure()
       {
          return unwrapImpl(this, CallbackProcedure.class);
       }

       /**
        * Unwrap this handle to a {@link Fillable} instance. If the handle is not a procedure handle
        * or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public Fillable unwrapFillable()
       {
          return unwrapImpl(this, Fillable.class);
       }

       /**
        * Unwrap this handle to a {@link Profiler} instance. If
        * the handle is not a Profiler handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Profiler unwrapProfiler()
       {
          return unwrapImpl(this, Profiler.class);
       }

       /**
        * Unwrap this handle to a {@link P2JQuery} instance. If the
        * handle is not a query handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public P2JQuery unwrapQuery()
       {
          return unwrapImpl(this, P2JQuery.class);
       }

       /**
        * Unwrap this handle to a {@link QueryAssociable} instance. If the
        * handle is not a query handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public QueryAssociable unwrapQueryAssociable()
       {
          return unwrapImpl(this, QueryAssociable.class);
       }

       /**
        * Unwrap this handle to a {@link IndexInformation} instance. If the
        * handle is not a query handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public IndexInformation unwrapIndexInformation()
       {
          return unwrapImpl(this, IndexInformation.class);
       }

       /**
        * Unwrap this handle to a {@link RcodeInfo} instance. If the
        * handle is not a <code>RcodeInfo</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public RcodeInfo unwrapRcodeInfo()
       {
          return unwrapImpl(this, RcodeInfo.class);
       }

       /**
        * Unwrap this handle to a {@link Remotable} instance. If the
        * handle is not a <code>Remotable</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Remotable unwrapRemotable()
       {
          return unwrapImpl(this, Remotable.class);
       }

       /**
        * Unwrap this handle to a {@link RemoveNode} instance. If the
        * handle is not a <code>RemoveNode</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public RemoveNode unwrapRemoveNode()
       {
          return unwrapImpl(this, RemoveNode.class);
       }

       /**
        * Unwrap this handle to a {@link ResultListHandler} instance. If the
        * handle is not a <code>ResultListHandler</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public ResultListHandler unwrapResultListHandler()
       {
          return unwrapImpl(this, ResultListHandler.class);
       }

       /**
        * Unwrap this handle to a {@link RequestResponseInfo} instance. If the
        * handle is not a <code>RequestResponseInfo</code> handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public RequestResponseInfo unwrapRequestResponseInfo()
       {
          return unwrapImpl(this, RequestResponseInfo.class);
       }

       /**
        * Unwrap this handle to a {@link SaxAttributes} instance. If the handle is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state of
        * the last used handle.
        *
        * @return   See above.
        */
       public SaxAttributes unwrapSaxAttributes()
       {
          return unwrapImpl(this, SaxAttributes.class);
       }

       /**
        * Unwrap this handle to a {@link SaxEntity} instance. If the handle is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state of
        * the last used handle.
        *
        * @return   See above.
        */
       public SaxEntity unwrapSaxEntity()
       {
          return unwrapImpl(this, SaxEntity.class);
       }

       /**
        * Unwrap this handle to a {@link SaxReader} instance. If the handle is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state of
        * the last used handle.
        *
        * @return   See above.
        */
       public SaxReader unwrapSaxReader()
       {
          return unwrapImpl(this, SaxReader.class);
       }

       /**
        * Unwrap this handle to a {@link SaxWriter} instance. If the handle is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state of
        * the last used handle.
        *
        * @return   See above.
        */
       public SaxWriter unwrapSaxWriter()
       {
          return unwrapImpl(this, SaxWriter.class);
       }

       /**
        * Unwrap this handle to a {@link Sensitive} instance. If the
        * handle is not a Sensitive handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Sensitive unwrapSensitive()
       {
          return unwrapImpl(this, Sensitive.class);
       }

       /**
        * Unwrap this handle to a {@link ControlFrame} instance. If the handle is not a ControlFrame
        * handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public ControlFrame unwrapControlFrame()
       {
          return unwrapImpl(this, ControlFrame.class);
       }

       /**
        * Unwrap this handle to a {@link EmailSender} instance. If the handle is not a EmailSender
        * handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public EmailSender unwrapEmailSender()
       {
          return unwrapImpl(this, EmailSender.class);
       }

       /**
        * Unwrap this handle to a {@link Enabled} instance. If the handle is not a Enabled
        * handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public Enabled unwrapEnabled()
       {
          return unwrapImpl(this, Enabled.class);
       }

       /**
        * Unwrap this handle to a {@link EventProcedure} instance. If the handle is not a event
        * procedure (for an async request) handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public EventProcedure unwrapEventProcedure()
       {
          return unwrapImpl(this, EventProcedure.class);
       }

       /**
        * Unwrap this handle to a {@link FWDTimer} instance. If the handle is not a FWDTimer
        * handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public FWDTimer unwrapFWDTimer()
       {
          return unwrapImpl(this, FWDTimer.class);
       }

       /**
        * Unwrap this handle to a {@link Down} instance. If the
        * handle is not a Down handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Down unwrapDown()
       {
          return unwrapImpl(this, Down.class);
       }

       /**
        * Unwrap this handle to a {@link Server} instance. If the handle is not a Server handle
        * or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public Server unwrapServer()
       {
          return unwrapImpl(this, Server.class);
       }

       /**
        * Unwrap this handle to a {@link SerializeHiddenable} instance. If the handle does not refer a
        * {@code SerializeHiddenable} object or is invalid an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation. This is needed because for
        * invalid handles, a stack of handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public SerializeHiddenable unwrapSerializeHiddenable()
       {
          return unwrapImpl(this, SerializeHiddenable.class);
       }

       /**
        * Unwrap this handle to a {@link CommonProcedure} instance. If the
        * handle is not the SESSION system handle or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonSession unwrapSession()
       {
          return unwrapImpl(this, CommonSession.class);
       }

       /**
        * Unwrap this handle to a {@link CommonSessionId} instance. If the
        * handle is not the SESSION system handle or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonSessionId unwrapCommonSessionId()
       {
          return unwrapImpl(this, CommonSessionId.class);
       }

       /**
        * Unwrap this handle to a {@link Sizeable} instance. If the
        * handle is not a procedure, widget, window or frame handle or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Sizeable unwrapSizeable()
       {
          return unwrapImpl(this, Sizeable.class);
       }

       /**
        * Unwrap this handle to a {@link Signature} instance. If the
        * handle is not a procedure, widget, window or frame handle or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Signature unwrapSignature()
       {
          return unwrapImpl(this, Signature.class);
       }

       /**
        * Unwrap this handle to a {@link Multiple} instance. If the
        * handle is not a procedure, widget, window or frame handle or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Multiple unwrapMultiple()
       {
          return unwrapImpl(this, Multiple.class);
       }

       /**
        * Unwrap this handle to a {@link SOAPEntity} instance. If the handle's resource is
        * not implementing the {@link SOAPEntity} interface or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public SOAPEntity unwrapSOAPEntity()
       {
          return unwrapImpl(this, SOAPEntity.class);
       }

       /**
        * Unwrap this handle to a {@link SOAPFault} instance. If the handle's resource is
        * not implementing the {@link SOAPFault} interface or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public SOAPFault unwrapSOAPFault()
       {
          return unwrapImpl(this, SOAPFault.class);
       }

       /**
        * Unwrap this handle to a {@link SOAPHeader} instance. If the handle's resource is
        * not implementing the {@link SOAPHeader} interface or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public SOAPHeader unwrapSOAPHeader()
       {
          return unwrapImpl(this, SOAPHeader.class);
       }

       /**
        * Unwrap this handle to a {@link SOAPHeaderEntry} instance. If the handle's resource is
        * not implementing the {@link SOAPHeaderEntry} interface or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public SOAPHeaderEntry unwrapSOAPHeaderEntry()
       {
          return unwrapImpl(this, SOAPHeaderEntry.class);
       }

       /**
        * Unwrap this handle to a {@link Socket} instance. If the
        * handle is not the SOCKET handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Socket unwrapSocket()
       {
          return unwrapImpl(this, Socket.class);
       }

       /**
        * Unwrap this handle to a {@link SocketListener} instance.
        * If the handle is not the SERVER-SOCKET handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public SocketListener unwrapSocketListener()
       {
          return unwrapImpl(this, SocketListener.class);
       }

       /**
        * Unwrap this handle to a {@link Spreadsheet} instance. If the handle is not a FWDTimer
        * handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public Spreadsheet unwrapSpreadsheet()
       {
          return unwrapImpl(this, Spreadsheet.class);
       }

       /**
        * Unwrap this handle to a {@link SslServerAttribute} instance. If the handle is not a
        * SslServerAttribute handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public SslServerAttribute unwrapSslServerAttribute()
       {
          return unwrapImpl(this, SslServerAttribute.class);
       }

       /**
        * Unwrap this handle to a {@link SubTypeAttribute} instance. If the handle is not a
        * SubTypeAttribute handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public SubTypeAttribute unwrapSubType()
       {
          return unwrapImpl(this, SubTypeAttribute.class);
       }

       /**
        * Unwrap this handle to a {@link Stream} instance. If the handle is not a
        * Stream handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public Stream unwrapStream()
       {
          Object val = this.get();
          if (val instanceof Stream)
          {
             return (Stream) val;
          }
          else
          {
             // ERROR is always raised - as 4GL doesn't allow to unwrap a STREAM-HANDLE if the handle
             // is not valid
             throw new ErrorConditionException(14263,
                                               "Invalid handle or handle type for STREAM-HANDLE (14263)");
          }
       }

       /**
        * Unwrap this handle to a {@link TempTable} instance. If the
        * handle is not a temporary handle or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public TempTable unwrapTempTable()
       {
          return unwrapImpl(this, TempTable.class);
       }

       /**
        * Unwrap this handle to a {@link EmptyTempTable} instance. If the
        * handle is not a temporary handle or is invalid,
        * an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public EmptyTempTable unwrapEmptyTempTable()
       {
          return unwrapImpl(this, EmptyTempTable.class);
       }

       /**
        * Unwrap this handle to a {@link TempTableDuplicator} instance. If the handle is not a
        * temporary handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public TempTableDuplicator unwrapTempTableDuplicator()
       {
          return unwrapImpl(this, TempTableDuplicator.class);
       }

       /**
        * Unwrap this handle to a {@link CreateLike} instance. If the handle is not a
        * temporary handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public CreateLike unwrapCreateLike()
       {
          return unwrapImpl(this, CreateLike.class);
       }

       /**
        * Unwrap this handle to a {@link TransactionResource} instance. If the handle is not a
        * Transaction handle or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public TransactionResource unwrapTransaction()
       {
          return unwrapImpl(this, TransactionResource.class);
       }

       /**
        * Unwrap this handle to a {@link CommonHandle} instance. If the
        * handle is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonHandle unwrapType()
       {
          return unwrapImpl(this, CommonHandle.class);
       }

       /**
        * Unwrap this handle to a {@link UniqueID} instance. If the handle is
        * not a UniqueID handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public UniqueID unwrapUniqueID()
       {
          return unwrapImpl(this, UniqueID.class);
       }

       /**
        * Unwrap this handle to a {@link XCommon} instance. If the handle is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state of
        * the last used handle.
        *
        * @return   See above.
        */
       public XCommon unwrapXCommon()
       {
          return unwrapImpl(this, XCommon.class);
       }

       /**
        * Unwrap this handle to a {@link XEntity} instance. If the
        * handle is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public XEntity unwrapXEntity()
       {
          return unwrapImpl(this, XEntity.class);
       }

       /**
        * Unwrap this handle to a {@link XDocument} instance. If the
        * handle is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public XDocument unwrapXDocument()
       {
          return unwrapImpl(this, XDocument.class);
       }

       /**
        * Unwrap this handle to a {@link XmlSchema} instance. If the
        * handle is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public XmlSchema unwrapXmlSchema()
       {
          return unwrapImpl(this, XmlSchema.class);
       }

       /**
        * Unwrap this handle to a {@link XNodeRef} instance. If the
        * handle is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public XNodeRef unwrapXNodeRef()
       {
          return unwrapImpl(this, XNodeRef.class);
       }

       /**
        * Unwrap this handle to a {@link WebContextResource} instance. If the
        * handle is not a widget handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public WebContextResource unwrapWebContext()
       {
          return unwrapImpl(this, WebContextResource.class);
       }

       /**
        * Unwrap this handle to a {@link CommonWidget} instance. If the
        * handle is not a widget handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonWidget unwrapWidget()
       {
          return unwrapImpl(this, CommonWidget.class);
       }

       /**
        * Unwrap this handle to a {@link SelectableText} instance. If the
        * handle is not a widget handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public SelectableText unwrapSelectableText()
       {
          return unwrapImpl(this, SelectableText.class);
       }

       /**
        * Unwrap this handle to a {@link BoxInterface} instance. If the
        * handle is not a widget handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public BoxInterface unwrapBox()
       {
          return unwrapImpl(this, BoxInterface.class);
       }

       /**
        * Unwrap this handle to a {@link MinHeightCharsInterface} instance. If the
        * handle is not a widget handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public MinHeightCharsInterface unwrapMinHeightChars()
       {
          return unwrapImpl(this, MinHeightCharsInterface.class);
       }

       /**
        * Unwrap this handle to a {@link BlankInterface} instance. If the
        * handle is not a widget handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public BlankInterface unwrapBlank()
       {
          return unwrapImpl(this, BlankInterface.class);
       }

       /**
        * Unwrap this handle to the calendar widget interface.
        *
        * @return   The calendar widget interface
        */
       public Calendar unwrapCalendar()
       {
          return unwrapImpl(this, Calendar.class);
       }

       /**
        * Unwrap this handle to the button-list widget interface (ButtonList).
        *
        * @return   The button-list widget interface
        */
       public ButtonList unwrapButtonList()
       {
          return unwrapImpl(this, ButtonList.class);
       }

       /**
        * Unwrap this handle to the button-list widget interface (ButtonListGroup).
        *
        * @return   The button-list widget interface
        */
       public ButtonListGroup unwrapButtonListGroup()
       {
          return unwrapImpl(this, ButtonListGroup.class);
       }

       /**
        * Unwrap this handle to the button-list widget interface (ButtonListGroupItem).
        *
        * @return   The button-list widget interface
        */
       public ButtonListGroupItem unwrapButtonListGroupItem()
       {
          return unwrapImpl(this, ButtonListGroupItem.class);
       }

       /**
        * Unwrap this handle to a {@link DeblankInterface} instance. If the
        * handle is not a widget handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public DeblankInterface unwrapDeblank()
       {
          return unwrapImpl(this, DeblankInterface.class);
       }

       /**
        * Unwrap this handle to a {@link DirectManipulation} instance. If the
        * handle is not a widget handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public DirectManipulation unwrapDirectManipulation()
       {
          return unwrapImpl(this, DirectManipulation.class);
       }

       /**
        * Unwrap this handle to a {@link Droppable} instance. If the
        * handle is not a widget handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Droppable unwrapDroppable()
       {
          return unwrapImpl(this, Droppable.class);
       }

       /**
        * Unwrap this handle to a {@link CommonWidget} instance. If the
        * handle is not a widget handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonListWidget<?> unwrapCommonListWidget()
       {
          return unwrapImpl(this, CommonListWidget.class);
       }

       /**
        * Unwrap this handle to a {@link RadioSetInterface} instance. If the
        * handle is not a widget handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public RadioSetInterface unwrapRadioSet()
       {
          return unwrapImpl(this, RadioSetInterface.class);
       }

       /**
        * Unwrap this handle to a {@link RectangleInterface} instance. If the
        * handle is not a widget handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        *
        * @return   The instance of RectangleInterface.
        */
       public RectangleInterface unwrapRectangle()
       {
          return unwrapImpl(this, RectangleInterface.class);
       }

       /**
        * Unwrap this handle to a {@link HasVisible} instance. If the
        * handle is not a handle with VISIBLE attribute or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public HasVisible unwrapVisible()
       {
          return unwrapImpl(this, HasVisible.class);
       }

       /**
        * Unwrap this handle to a {@link CommonWindow} instance. If the
        * handle is a window handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public CommonWindow unwrapWindow()
       {
          return unwrapImpl(this, CommonWindow.class);
       }

       /**
        * Unwrap this handle to a {@link Coordinates} instance. If the
        * handle is a window handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method
        * invocation.  This is needed because for invalid handles, a stack of
        * handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public Coordinates unwrapCoordinates()
       {
          return unwrapImpl(this, Coordinates.class);
       }

       /**
        * Unwrap this handle to a {@link com.goldencode.p2j.persist.XmlNode XmlNode} instance.
        * If the handle is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state
        * of the last used handle.
        *
        * @return   See above.
        */
       public XmlNode unwrapXmlNode()
       {
          return unwrapImpl(this, XmlNode.class);
       }

       /**
        * Unwrap this handle to a {@link com.goldencode.p2j.persist.XmlData XmlData} instance.
        * If the handle is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state
        * of the last used handle.
        *
        * @return   See above.
        */
       public XmlData unwrapXmlData()
       {
          return unwrapImpl(this, XmlData.class);
       }

       /**
        * Unwrap this handle to a {@link FwdReport} instance. If the handle is
        * not a Report handle or is invalid, an
        * {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public FwdReport unwrapFwdReport()
       {
          return unwrapImpl(this, FwdReport.class);
       }

       /**
        * Unwrap this handle to a {@link com.goldencode.p2j.ui.WriteProtectable} instance.
        * If the handle is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is
        * needed because for invalid handles, a stack of handles is maintained, to know the state
        * of the last used handle.
        *
        * @return   See above.
        */
       public WriteProtectable unwrapWriteProtectable()
       {
          return unwrapImpl(this, WriteProtectable.class);
       }

       /**
        * Unwrap this handle to a {@link TreeFace} instance. If the handle is not {@link TreeFace} or is
        * invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public TreeFace unwrapTreeFace()
       {
          return unwrapImpl(this, TreeFace.class);
       }

       /**
        * Unwrap this handle to a {@link TreeList} instance. If the handle is not {@link TreeList} or is
        * invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public TreeList unwrapTreeList()
       {
          return unwrapImpl(this, TreeList.class);
       }

       /**
        * Unwrap this handle to a {@link TreeNodeCollection} instance. If the handle is not
        * {@link TreeNodeCollection} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public TreeNodeCollection unwrapTreeNodeCollection()
       {
          return unwrapImpl(this, TreeNodeCollection.class);
       }

       /**
        * Unwrap this handle to a {@link TreeView} instance. If the handle is not {@link TreeView} or is
        * invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public TreeView unwrapTreeView()
       {
          return unwrapImpl(this, TreeView.class);
       }

       /**
        * Unwrap this handle to a {@link TreeNodeFace} instance. If the handle is not {@link TreeNodeFace} or is
        * invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public TreeNodeFace unwrapTreeNodeFace()
       {
          return unwrapImpl(this, TreeNodeFace.class);
       }

       /**
        * Unwrap this handle to a {@link Nodes} instance. If the handle is not {@link Nodes} or is
        * invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public Nodes unwrapNodes()
       {
          return unwrapImpl(this, Nodes.class);
       }

       /**
        * Unwrap this handle to a {@link TabSet} instance. If the handle is not {@link TabSet} or is
        * invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public TabSet unwrapTabSet()
       {
          return unwrapImpl(this, TabSet.class);
       }

       /**
        * Unwrap this handle to a {@link HtmlBrowser} instance. If the handle is not
        * {@link HtmlBrowser} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public HtmlBrowser unwrapHtmlBrowser()
       {
          return unwrapImpl(this, HtmlBrowser.class);
       }

       /**
        * Unwrap this handle to a {@link ProgressBar} instance. If the handle is not
        * {@link ProgressBar} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public ProgressBar unwrapProgressBar()
       {
          return unwrapImpl(this, ProgressBar.class);
       }

       /**
        * Unwrap this handle to a {@link PrimaryIndex} instance. If the handle is not
        * {@link PrimaryIndex} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public PrimaryIndex unwrapPrimary()
       {
          return unwrapImpl(this, PrimaryIndex.class);
       }

       /**
        * Unwrap this handle to a {@link OcxMouse} instance. If the handle is not
        * {@link OcxMouse} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public OcxMouse unwrapOcxMouse()
       {
          return unwrapImpl(this, OcxMouse.class);
       }

       /**
        * Unwrap this handle to a {@link OcxDragDrop} instance. If the handle is not
        * {@link OcxDragDrop} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public OcxDragDrop unwrapOcxDragDrop()
       {
          return unwrapImpl(this, OcxDragDrop.class);
       }

       /**
        * Unwrap this handle to a {@link Rejectable} instance. If the handle is not
        * {@link Rejectable} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public Rejectable unwrapRejectable()
       {
          return unwrapImpl(this, Rejectable.class);
       }

       /**
        * Unwrap this handle to a {@link DataObject} instance. If the handle is not
        * {@link DataObject} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public DataObject unwrapDataObject()
       {
          return unwrapImpl(this, DataObject.class);
       }

       /**
        * Unwrap this handle to a {@link DataSetInterface} instance. If the handle is not
        * {@link DataSetInterface} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public DataSetInterface unwrapDataSet()
       {
          return unwrapImpl(this, DataSetInterface.class);
       }

       /**
        * Unwrap this handle to a {@link IterCounter} instance. If the handle is not {@link IterCounter} or is
        * invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation. This is needed because for
        * invalid handles, a stack of handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public IterCounter unwrapIterCounter()
       {
          return unwrapImpl(this, IterCounter.class);
       }

       /**
        * Unwrap this handle to a {@link RefCounter} instance. If the handle is not {@link RefCounter} or is
        * invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation. This is needed because for
        * invalid handles, a stack of handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public RefCounter unwrapRefCounter()
       {
          return unwrapImpl(this, RefCounter.class);
       }

       /**
        * Unwrap this handle to a {@link DataSetChangeable} instance. If the handle is not
        * {@link DataSetChangeable} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public DataSetChangeable unwrapDataSetChangeable()
       {
          return unwrapImpl(this, DataSetChangeable.class);
       }

       /**
        * Unwrap this handle to a {@link DataSourceModifiable} instance. If the handle is not
        * {@link DataSourceModifiable} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation. This is needed because for
        * invalid handles, a stack of handles is maintained, to know the state of the last used handle.
        *
        * @return   See above.
        */
       public DataSourceModifiable unwrapDataSourceModifiable()
       {
          return unwrapImpl(this, DataSourceModifiable.class);
       }

       /**
        * Unwrap this handle to a {@link DataRelationInterface} instance. If the handle is not
        * {@link DataRelationInterface} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public DataRelationInterface unwrapDataRelation()
       {
          return unwrapImpl(this, DataRelationInterface.class);
       }

       /**
        * Unwrap this handle to a {@link DataSourceInterface} instance. If the handle is not
        * {@link DataSourceInterface} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public DataSourceInterface unwrapDataSource()
       {
          return unwrapImpl(this, DataSourceInterface.class);
       }

       /**
        * Unwrap this handle to a {@link JsonData} instance. If the handle is not
        * {@link JsonData} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is
        * returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public JsonData unwrapJsonData()
       {
          return unwrapImpl(this, JsonData.class);
       }

       /**
        * Unwrap this handle to a {@link CommonSecurityPolicy} instance. If the handle is not
        * {@link CommonSecurityPolicy} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public CommonSecurityPolicy unwrapSecurityPolicy()
       {
          return unwrapImpl(this, CommonSecurityPolicy.class);
       }

       /**
        * Unwrap this handle to a {@link CommonAuditPolicy} instance. If the handle is not
        * {@link CommonAuditPolicy} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public CommonAuditPolicy unwrapAuditPolicy()
       {
          return unwrapImpl(this, CommonAuditPolicy.class);
       }

       /**
        * Unwrap this handle to a {@link CommonAuditControl} instance. If the handle is not
        * {@link CommonAuditControl} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public CommonAuditControl unwrapAuditControl()
       {
          return unwrapImpl(this, CommonAuditControl.class);
       }

       /**
        * Unwrap this handle to a {@link CustomFont} instance. If the handle is not
        * {@link CustomFont} or is invalid, an {@link #invalidAttrAccessProxy dynamic proxy}
        * is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public CustomFont unwrapCustomFont()
       {
          return unwrapImpl(this, CustomFont.class);
       }

       /**
        * Unwrap this handle to a {@link ImageList} instance. If the handle is not {@link ImageList} or is
        * invalid, an {@link #invalidAttrAccessProxy dynamic proxy} is returned.
        * <p>
        * Each unwrap call must be followed by an actual attribute/method invocation.  This is needed
        * because for invalid handles, a stack of handles is maintained, to know the state of the last
        * used handle.
        *
        * @return   See above.
        */
       public ImageList unwrapImageList()
       {
          return unwrapImpl(this, ImageList.class);
       }

       /**
        * Gets the instance of WidgetExtension.
        *
        * @return   The instance of WidgetExtension
        */
       public WidgetExtension unwrapWidgetExtension()
       {
          return unwrapImpl(this, WidgetExtension.class);
       }

       /**
        * Gets the instance of WithCaption.
        *
        * @return   The instance of WithCaption
        */
       public WithCaption unwrapWithCaption()
       {
          return unwrapImpl(this, WithCaption.class);
       }

       /**
        * Creates a new instance of the same type that represents the
        * <code>unknown value</code>.
        *
        * @return   An instance that represents the <code>unknown value</code>.
        */
       public BaseDataType instantiateUnknown()
       {
          return new handle();
       }

       /**
        * Creates a new instance of the same type that represents the default initialized value.
        *
        * @return   An instance that represents the default value.
        */
       @Override
       public BaseDataType instantiateDefault()
       {
          return new handle();
       }

       /**
        * Does the same as standard <code>clone()</code> method but returns an
        * instance of <code>BaseDataType</code> and doesn't throw the
        * <code>CloneNotSupportedException</code>.
        *
        * @return   A clone of this instance.
        */
       public handle duplicate()
       {
          return new handle(this);
       }

       /**
        * Hash code implementation which is consistent with {@link
        * BaseDataType#equals}.
        *
        * @return  Hash code value for this object instance.
        */
       public int hashCode()
       {
          if (isUnknown())
          {
             return ResourceIdHelper.UNKNOWN_STRING.hashCode();
          }

          Long resId = resourceId(this.value);
          return resId.hashCode();
       }

       /**
        * Returns the value of this instance as an <code>Object</code>.
        * <p>
        * If this instance represents the <code>unknown value</code>, a
        * <code>null</code> will be returned.
        *
        * @return   The value as an <code>Object</code> or <code>null</code> if
        *           this is <code>unknown</code>.
        */
       public Object get()
       {
          Object result = value;

          // redirect to contained object if it is the special wrapper
          if (result instanceof TransparentWrapper)
          {
             TransparentWrapper wrap = (TransparentWrapper) result;
             result = wrap.get();
          }

          return result;
       }

       /**
        * Set the value of this instance as a {@link WrappedResource}.
        *
        * @param    value
        *           The value to be represented in this instance.
        */
       public void set(WrappedResource value)
       {
          if (isUndoable())
          {
             checkUndoable(() -> new handle(value));
          }

          possibleChained = false;

          // TODO: an attempt was made to hide this via a MutableReference interface, but there were
          //       some problems with the proxy creations (maybe because the interface used generics)
          if (value instanceof BufferImpl)
          {
             this.value = ((BufferImpl) value).ref();
          }
          else if (value instanceof DataSet)
          {
             this.value = ((DataSet) value).ref();
          }
          else if (value instanceof POJOComObject)
          {
             this.value = (WrappedResource) ((POJOComObject) value).getComObjectInstance();
          }
         else
          {
             this.value = value;
          }
       }

       /**
        * Determines if this instance is valid (to be used).
        *
        * @return   <code>true</code> if this instance can be used.
        */
       public logical isValid()
       {
          return logical.of(_isValid());
       }

       /**
        * Verifies whether the specified event is valid for the widget referenced by this handle. For
        * each type of widget, only certain events are valid. Corresponds VALID-EVENT function.
        *
        * @param   event
        *          Name of the event.
        *
        * @return  <code>true</code> if this handle references a widget and the specified event is
        *          valid for this type of widgets.
        */
       public logical isValidEvent(character event)
       {
          return logical.of(_isValidEvent(event));
       }

       /**
        * Verifies whether the specified event is valid for the widget referenced by this handle. For
        * each type of widget, only certain events are valid. Corresponds VALID-EVENT function.
        *
        * @param   event
        *          Name of the event.
        *
        * @return  <code>true</code> if this handle references a widget and the specified event is
        *          valid for this type of widgets.
        */
       public logical isValidEvent(String event)
       {
          return isValidEvent(new character(event));
       }

       /**
        * Determines if this instance is valid (to be used).
        *
        * @return   boolean <code>true</code> if this instance can be used.
        */
       public boolean _isValid()
       {
          return (value != null) && value.valid();
       }

       /**
        * Verifies whether the specified event is valid for the widget referenced by this handle. For
        * each type of widget, only certain events are valid. Corresponds VALID-EVENT function.
        *
        * @param   event
        *          Name of the event.
        *
        * @return  <code>true</code> if this handle references a widget and the specified event is
        *          valid for this type of widgets.
        */
       public boolean _isValidEvent(String event)
       {
          return _isValidEvent(new character(event));
       }

       /**
        * Verifies whether the specified event is valid for the widget referenced by this handle. For
        * each type of widget, only certain events are valid. Corresponds VALID-EVENT function.
        *
        * @param   event
        *          Name of the event.
        *
        * @return  <code>true</code> if this handle references a widget and the specified event is
        *          valid for this type of widgets.
        */
       public boolean _isValidEvent(character event)
       {
          UnimplementedFeature.missing("VALID-EVENT function is not implemented");
          return true;
       }

       /**
        * Determines if this instance represents the <code>unknown value</code>.
        *
        * @return   <code>true</code> if this instance is set to the
        *           <code>unknown value</code>.
        */
       public boolean isUnknown()
       {
          return (value == null || value.unknown());
       }

       /**
        * Sets the state of this instance's <code>unknown value</code> flag to
        * <code>true</code>.
        * <p>
        * <b>Warning: a separate call is needed to ensure that the data of this
        * instance is set to the correct value.</b>
        */
       public void setUnknown()
       {
          if (!isUnknown())
          {
             checkUndoable(true);
          }

          value = null;
       }

       @Override
       protected boolean isIncompatibleTypesOnConversion(BaseDataType value)
       {
          // invalid conversion is being thrown even if unknown
          if (value instanceof longchar || value instanceof clob || value instanceof blob)
          {
             incompatibleTypesOnConversion();
          }

          return super.isIncompatibleTypesOnConversion(value);
       }

       /**
        * Sets the state (data and unknown value) of this instance based on the state of the passed
        * instance.
        * <p>
        * If the value is not of type <code>handle</code>, the following automatic type
        * conversion will occur:
        * <p>
        * <pre>
        * unknown - The instance will be set to unknown value.
        * handle  - The wrapped value will be assigned as expected.
        * </pre>
        * <p>
        * All other cases will generate an error.
        * <p>
        * This variant is meant to handle the cases of built-in functions and methods in the 4GL
        * which have polymorphic return types (e.g. DYNAMIC-FUNCTION()). This should NOT be used for
        * non-polymorphic assignments.
        *
        * @param    value
        *           The instance from which to copy state.
        */
       public void assign(BaseDataType value)
       {
          possibleChained = false;

          if (value == null)
          {
             setUnknown();
             return;
          }

          // the value may be a proxy; make sure to unwrap and work with the real value
          value = value.val();

          if (value.isUnknown())
          {
             setUnknown();
          }
          else if (value instanceof handle)
          {
             assign((handle) value);
          }
          else if (value instanceof character)
          {
             assign(fromString((character) value));
          }
          else if (value instanceof int64)
          {
             assign(fromResourceId(((int64) value).longValue()));
          }
          else if (value instanceof logical || value instanceof date || value instanceof decimal)
          {
             assign(fromResourceId((new integer(value)).longValue()));
          }
          else if (value instanceof comhandle)
          {
             assign(((comhandle)value).value);
          }
          else
          {
             incompatibleTypesOnConversion();
          }
       }

       /**
        * Sets the state (data and unknown value) of this instance based on the
        * state of the passed instance.
        *
        * @param    value
        *           The instance from which to copy state.
        */
       public void assign(handle value)
       {
          // the value may be a proxy; make sure to unwrap and work with the real value
          if (BaseDataType.isProxy(value))
          {
             assign(value.val());
          }
          else
          {
             assign(value.value);
          }
       }

       /**
        * Sets the state (data and unknown value) of this instance based on the
        * state of the passed instance.
        *
        * @param    value
        *           The instance from which to copy state.
        */
       public void assign(WrappedResource value)
       {
          set(value);
       }

       /**
        * Sets the state (data and unknown value) of this instance based on the
        * state of the passed instance.
        *
        * @param    value
        *           The instance from which to copy state.
        */
       public void assign(Stream value)
       {
          set(new TransparentWrapper(value));
       }

       /**
        * Sets the state (data and unknown value) of this instance based on the
        * state of the passed instance.
        *
        * @param    value
        *           The instance from which to copy state. This must be of
        *           type <code>handle</code> or <code>WrappedResource</code>.
        */
       public void assign(Object value)
       {
          if (value == null)
          {
             setUnknown();
             return;
          }

          if (value instanceof WrappedResource)
          {
             assign((WrappedResource) value);
          }
          else if (value instanceof handle)
          {
             assign((handle) value);
          }
          else if (value instanceof CommonFrame)
          {
             value = ((CommonFrame) value).asWidget();

             assign((WrappedResource) value);
          }
          else
          {
             // unexpected failure
             throw new IllegalArgumentException("Invalid value type.");
          }
       }

       /**
        * Sets the state (data and unknown value) of this instance based on the
        * state of the passed instance.
        *
        * @param    value
        *           The instance from which to copy state.
        */
       public void assign(Undoable value)
       {
          assign((handle) value);
       }

       /**
        * Compares this instance with the specified instance and returns a -1
        * if this instance is less than the specified, 0 if the two instances
        * are equal and 1 if this instance is greater than the specified
        * instance.  This is the implementation of the <code>Comparable</code>
        * interface.
        * <p>
        * The algorithm will fail to give meaningful results in the case where
        * one tries to sort against other objects that do not represent compatible
        * values.
        *
        * @param    obj
        *           The instance to compare against.
        *
        * @return   0 or 1 depending on if the passed instance is or is not
        *           <code>unknown</code>.
        */
       public int compareTo(Object obj)
       {
          Long bdtValue = null;
          Long resourceId = resourceId(getResource());

          // handle is also a BDT type
          if (obj instanceof BaseDataType)
          {
             BaseDataType bdt = (BaseDataType) obj;

             // two unknown values are equals
             if (isUnknown() || bdt.isUnknown())
             {
                // an unknown handle is greater than a known handle
                return Boolean.compare(isUnknown(), bdt.isUnknown());
             }

             if (bdt instanceof handle)
             {
                // handle
                bdtValue = resourceId(((handle) bdt).getResource());
             }
             else
             {
                // this path is only used when type morphing is needed
                // ResourceIdHelper.idFromString could throw an ErrorConditionException
                try
                {
                   if (bdt instanceof date && !(bdt instanceof datetime))
                   {
                      // date values only
                      bdtValue = ((date) bdt).longValue();
                   }
                   if (bdt instanceof logical)
                   {
                      // logical values
                      bdtValue = ((logical) bdt).booleanValue() ? 1L : 0L;
                   }
                   else if (bdt instanceof NumberType)
                   {
                      // decimal, integer, int64, recid
                      bdtValue = ResourceIdHelper.idFromString(((NumberType) bdt).toStringMessage());
                   }
                   else if (bdt instanceof Text)
                   {
                      // character or longchar values can be converted
                      bdtValue = ResourceIdHelper.idFromString(((Text) bdt).toStringMessage());
                   }
                }
                finally
                {
                   // nothings
                }
             }
          }

          // If BDT value is null conversion is not possible.
          if (bdtValue == null)
          {
             incompatibleTypesOnConversion();
          }
          else
          {
             return resourceId.compareTo(bdtValue);
          }

          return -1;
       }

       /**
        * Checks whether the resource object is of a specified type (case insensitive). If the handle
        * is not valid or the resource is does not have a {@code TYPE} attribute, the method returns
        * {@code false}.
        *
        * @param   someType
        *          The type to check. Use the constants defined in {@link LegacyResource} to check
        *          the type of the resource.
        *
        * @return  {@code true} if the type of this object matches the specified one.
        */
       public boolean isType(String someType)
       {
          if (_isValid() && value instanceof CommonHandle)
          {
             return ((CommonHandle) value).resourceType().toStringMessage()
                                          .equalsIgnoreCase(someType);
          }

          // invalid handle or not a typed resource
          return false;
       }

       /**
        * Indicate if in a {@code RUN ... PERSISTENT SET} statement, this handle should receive
        * the resource before the called procedure is executed (this returns {@code false}) or
        * after the called procedure is executed (this returns {@code true}).
        * Naturally, program handle variables are set before the called procedure is executed, so
        * this should return {@code false}.
        *
        * @return   {@code true} if the handle should be set after the called procedure is executed.
        */
       public boolean delayPersistentSet()
       {
          return false;
       }

       /**
        * Creates a string representation of the instance data using the format
        * {@link ResourceIdHelper#DEFAULT_FORMAT}. If the instance represents the
        * <code>unknown value</code>, a '?' will be returned.
        *
        * @return   The formatted string.
        */
       public String toString()
       {
          return toString(null);
       }

       /**
        * Creates a string representation of the instance data using the user
        * specified format string (Progress 4GL compatible) or if no such string
        * is provided, the default format of {@link ResourceIdHelper#DEFAULT_FORMAT}.
        * If the instance represents the <code>unknown value</code>, a '?' will be
        * returned.
        *
        * @param    fmt
        *           The Progress 4GL format string or <code>null</code> if the
        *           default format is to be used.
        *
        * @return   The formatted string.
        */
       public String toString(String fmt)
       {
          if (isUnknown())
          {
             return ResourceIdHelper.UNKNOWN_STRING;
          }

          Long id = resourceId(value);

          return ResourceIdHelper.idToString(fmt, id);
       }

       /**
        * Creates a string representation of the instance data in a form that is
        * compatible with the <code>MESSAGE</code> language statement.  If the
        * instance represents the <code>unknown value</code>, a '?' will be
        * returned.
        *
        * @return   The 'message' formatted string.
        */
       public String toStringMessage()
       {
          return toString();
       }

       /**
        * Creates a string representation of the instance data using the 'export'
        * format.  If the instance represents the <code>unknown value</code>, a
        * '?' will be returned.
        *
        * @return   The 'export' formatted string.
        */
       public String toStringExport()
       {
          return toString();
       }

       /**
        * Return the default display format string for this type.
        * <p>
        * Warning: this is larger than the Progress version because the range of
        * handle values can be a 64-bit integer in this implementation.
        *
        * @return   The default format string.
        */
       public String defaultFormatString()
       {
          return ResourceIdHelper.DEFAULT_FORMAT;
       }

       /**
        * Replacement for the default object reading method. The latest
        * state is read from the input source.
        *
        * @param    in
        *           The input source from which fields will be restored.
        *
        * @throws   IOException
        *           In case of I/O errors.
        * @throws   ClassNotFoundException
        *           If payload can't be instantiated.
        */
       public void readExternal(ObjectInput in)
       throws IOException,
              ClassNotFoundException
       {
          assign(fromString(readString(in)));
       }

       /**
        * Replacement for the default object writing method. The latest
        * state is written to the output destination.
        *
        * @param    out
        *           The output destination to which fields will be saved.
        *
        * @throws   IOException
        *           In case of I/O errors.
        */
       public void writeExternal(ObjectOutput out)
       throws IOException
       {
          writeString(out, toString());
       }

       /**
        * Getter for the wrapped resource.
        *
        * @return   The {@link #value resource}.
        */
       public WrappedResource getResource()
       {
          return value;
       }

       /**
        * Get resource ID as a long value.
        *
        * @return  Resource ID if any or null.
        *
        */
       public Long getResourceId()
       {
          return isUnknown() ? null : handle.resourceId(value);
       }

       /**
        * Identify if this data is dependent upon the context local. This identifies
        * if the data is safe to be cached in cross-session places or the data should
        * not leak from the context. If is is not safe to be shared cross-session, then
        * this should return {@code null}. If other representation is suitable for caching,
        * then this can return another object that wraps internal values that are not
        * dependent upon the context (e.g. date, date-time, date-time-tz).
        *
        * @return   Always. {@code null}.
        */
       @Override
       public Object getIndependentFromContext()
       {
          return null;
       }

       /**
        * Helper to expose APIs which have direct access to the context-local state.
        */
       public static class Helper
       {
          /** The {@link WorkArea} instance. */
          private final WorkArea wa;

          /**
           * Create a new instance and associate the given WorkArea instance.
           *
           * @param    wa
           *           The {@link WorkArea} instance.
           */
          private Helper(WorkArea wa)
          {
             this.wa = wa;
          }

          /**
           * Remove the given resource from the context-local map of all resource.
           * <p>
           * This method should be called by all wrapped resources when deleted,
           * that is all resources implementing {@link WrappedResource} interface.
           *
           * @param    resource
           *           A resource instance to be removed.
           */
          public void removeResource(WrappedResource resource)
          {
             if (resource == null)
             {
                return;
             }

             Long id = wa.resourceIds.remove(resource);
             if (id != null)
             {
                wa.idResources.remove(id);
             }
          }
       }

       /**
        * Stores global data relating to the state of the current context.
        */
       private static class WorkArea
       {
          /**
           * Stores handles that have been converted to strings and may need
           * to be converted back into a handle.
           */
          private final Map<Long, WrappedResource> idResources = new HashMap<>();

          /**
           * Map of resources and their resource ids. Resource ids are tracked
           * here because they are naturally related to handles.
           */
          private final Map<WrappedResource, Long> resourceIds = new /*Weak*/HashMap<>();

          private final ArrayDeque<handle> invalidCalls = new ArrayDeque<>();

          /** The next resource ID to allocate. */
          private long nextId = 1000;
       }

       /**
        * Handler for the {@link #invalidAttrAccessProxy} proxy.
        */
       public static class InvalidAttributeAccess
       implements InvocationHandler
       {
          /**
           * This proxy is used only for cases when the handle is invalid or not of the expected type.
           */
          @Override
          public Object invoke(Object proxy, Method method, Object[] args)
          throws Throwable
          {
             WorkArea wa = work.get();

             BaseDataType unkn = null;
             Class<?> ret = method.getReturnType();

             if (ret == BaseDataType.class)
             {
                if ("dereference".equals(method.getName()) && args.length > 0 && args[0] instanceof Class)
                {
                   unkn = BaseDataType.generateUnknown((Class<?>) args[0]);
                }
                else
                {
                   unkn = unknown.UNKNOWN;
                }
             }
             else if (BaseDataType.class.isAssignableFrom(ret))
             {
                unkn = (BaseDataType) BaseDataTypeFactory.instantiate(ret);
             }

             // valid handle, wrong API, show error
             handle h = wa.invalidCalls.pop();
             if (h.possibleChained)
             {
                h.possibleChained = false;
                ErrorManager.recordOrThrowError(10068);
                // Lead attributes in a chained-attribute expression (a:b:c) must be type HANDLE or a user-defined type and valid (not UNKNOWN).
             }
             else
             {
                handle.invalidAttribute(handle.getAttrOrMethodName(method, args), h, ret == Void.TYPE);
             }
             return unkn;
          }
       }

       /**
        * A pseudo-resource with a set id. This type of resources should be used
        * when retrieving handles from database records. In this case, if the handle
        * is invalid, a dummy resource with a set id should be returned, instead of
        * a "zero" resource. The "zero" resource is returned when explicitly converting
        * strings to handles.
        */
       private static class DummyResource
       implements WrappedResource
       {
          /** The set id of the resource */
          private final Long id;

          /**
           * Basic constructor.
           *
           * @param   id
           *          The id of this dummy resource.
           */
          public DummyResource(Long id)
          {
             this.id = id;
          }

          /**
           * This type of resource should be considered invalid at any time.
           */
          @Override
          public boolean valid()
          {
             return false;
          }

          /**
           * This type of resource is not unknown, but only invalid.
           */
          @Override
          public boolean unknown()
          {
             return false;
          }

          /**
           * Retrieves the id of the resource.
           *
           * @return   The id of the resource.
           */
          @Override
          public Long id()
          {
             return id;
          }

          /**
           * Sets the id of the resource. This should be a no-op as the id should be set
           * only once in the constructor.
           */
          @Override
          public void id(long id)
          {
             // no-op
          }
       }

       /**
        * A "zero" pseudo-resource. A "zero" resource is used for handles created by
        * the {@link handle#fromString(String)} method when a formally valid ID is
        * provided, but the ID doesn't denote a valid resource.
        * <p>
        * A zero resource is not valid but is not unknown.
        */
       private static final WrappedResource ZERO_RESOURCE = new WrappedResource()
       {
          @Override
          public boolean valid()
          {
             return false;
          }

          @Override
          public boolean unknown()
          {
             return false;
          }

          @Override
          public Long id()
          {
             return 0L;
          }

          @Override
          public void id(long id)
          {
             // no-op
          }
       };
    }