d061201h-0.52beta-DropNotes.txt 0.01 UTF-8 dh:2007-02-05 STABILIZATION NOTE ODMJNI 1.0 0.52beta Windows Handle Stabilization ------------------------------------------------ For the latest version of this material, consult web page . This material is maintained on the ODMA Interoperability Exchange site at . The 0.60beta release of ODMJNI 1.0 is made up of a series of drops that complete the stabilization of functionality on an area. These are focused increments that stabilize around a particular function. The 0.52beta drop is the first increment beyond the 0.50beta Feature- Complete release. This drop stabilizes the association of ODMA DMS dialog windows with the windows of the ODMA-aware Java application. CONTENT Synopsis 1. Requirement 2. Approach 3. Changes 3.1 OdmNative100 3.2 odmjni100 3.3 System setup and integration 4. Confirmation of Changes 4.1 Regression check 4.2 Correction confirmation 4.3 OdmNative confirmation Copyright Notice Attribution Revision History 1. REQUIREMENT The ODMA DMS must be informed of the Microsoft Windows native window handle (HWND value) of the Java application at the time that the connection with the ODMA DMS is established. Modal dialogs displayed by the DMS will then be correctly associated with the correct application window on the GUI desktop. 2. APPROACH 0.52beta introduces an alternative method for creating an ODMJNI connection: import info.odma.practical100.*; import info.odma.odmjni100.*; OdmConnection MyOdma = OdmJniBind.application ( java.lang.String myAppId, java.awt.Window myAppWindow ); where the myAppWindow parameter is a reference to the the AWT Window instance (or subclass) that corresponds to the main Window of the application. This window must already exist and should already be displayed when the OdmJniBind.application operation is performed. The implementation of the OdmConnection interface and any further interfaces obtained from it must all have their release() methods performed before the window is closed and the application terminated. ODMJNI now determines the native GUI window that is used in the underlying implementation and retains that Windows handle for communication to every ODMA DMS that is used during the lifetime of the connection. 3. CHANGES 3.1 OdmNative100 The OdmBindNative100 factory function is extended to have an additional HWND parameter that is the Windows handle of a native window to be used as the main application window of modal dialogs from any ODMA DMS used via the implemented IodmApplication100 interface and any other interface implementations obtained from it. The supplied HWND parameter may be NULL. There are no changes to OdmNative100 interfaces themselves. Whenever it is necessary to connect with a DMS via the ODMA Connection Manager (using the ODMRegisterApp API function), the supplied HWND value is passed as a parameter. If the supplied HWND value is NULL, OdmNative100 will attempt to obtain a suitable HWND by an internal heuristic. This heuristic is only reliable for console applications and some Windows GUI applications, not Java GUI applications. 3.2 odmjni100 The OdmJniBind.application(java.lang.String myAppId) operation is modifed to supply a NULL HWND parameter to OdmJniBindNative100 in its getIodmNative implementation. The new OdmJniBind.application(myAppId, myAppWindow) uses a different native method, getIodmWinNative, that determines the Windows handle of the supplied java.awt.Window instance. This native implementation relies on features JNI AWT libraries to access the AWT implementation and retrieve native Windows information from the implementation. 3.3 System Setup and Integration The use of Java AWT libraries requires some additional setup and integration. These changes are incorporated in the scripts that are updated in the 0.52beta drop: 3.3.1 Building odmjni100.dll. The DLL construction requires additional headers plus the jawt.lib file that is part of the JDK \lib directory. The BuildDLL.bat script is updated to incorporate the additional library files (using an options file, odmjni100.opt). The OdmJNI.bat script is modified to provide the additional LIB path. 3.3.2 Running ODMJNI Applications. The odmjni100.dll now depends on the jawt.dll that is part of the JDK \jre\bin directory. The OdmJava.bat script is updated to add that directory to the PATH environment variable. Similar provisions must be made in deployment of ODMJNI for use with a particular Java runtime. 4. CONFIRMATION OF CHANGES 4.1 Regression Check An additional Java Swing test directory, test\CheckSwing, is added to the odmjni100 test suite. The program OdmClicker creates a minimal Swing window that steps through OdmConnection interface operations. The presentation of DMS document-selection dialogs repeats until "Cancel" is selected. OdmClicker is not a demonstration of full and correct ODMA-aware operation. The only purpose is to obtain a connection and cause DMS dialogs to appear. The initial version worked with the 0.50beta release and functioned correctly except the new application(myAppId, myAppWindow) operation is not used. 4.2 Correction Confirmation After the the changes were made to OdmNative100 and odmjni100, the OdmClicker was modified to use the new OdmJniBind.application method. This modification confirms that the proper hWnd parameter is now being passed down to ODMA for use by the ODMA DMS integrations. 4.3 OdmNative Confirmation There is no independent test at the OdmNative100 level. The change at this level is too simple to require an independent test program until the OdmNative100 library is tested for wider use in native Windows applications. - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - Questions, comments, discussion and feedback about ODMA concepts, status, and materials are welcome. Please send comments to the discussion list at . For further details visit . Copyright © 2007 NuovoDoc This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit web site http://creativecommons.org/licenses/by/2.5/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA. Attributions can be made in any suitable scholarly-citation format. It is requested that citations identify the material sufficiently for others to be able to locate the material on their own. This citation example can be adapted to your purpose and format: Hamilton, Dennis E. Stabilization Note: ODMJNI 1.0 0.52beta Windows Handle Stabiliza- tion, ODMA Interoperability Exchange, ODMdev Development Note page d061201h-0.52beta-DropNotes.txt 0.01, February 5, 2007. Current version available as part of the archive downloadable at . - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - 0.01 2007-02-05-22:30 Update to reflect the final status of 0.52beta 0.00 2007-01-14-19:15 Sketch the 0.52beta Drop stabilization of Windows handle location for use in making reliable DMS Dialog displays. $Header: /ODMdev/d061201h-0.52beta-DropNotes.txt 2 07-02-05 22:32 Orcmid $ *** END OF d061201h-0.52beta-DropNotes.txt ***