yinet2020
/
ytj_Jx


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275
							<HTML>

<BODY>
	Jacob is a Java library that lets Java applications communicate with Microsoft Windows DLLs or COM libraries. It does this
	through the use of a custom DLL that the Jacob Java classes communicate with via JNI. The library and dll isolate the Java
	developer from the underlying windows libraries so that the Java developer does not have to write custom JNI code.
	<p></p>
	Jacob is not used for creating ActiveX plugins or other modules that live inside of Microsoft Windows applications.
	<hr>

	<h2> The Jacob Packages </h2>

	The JACOB jar contains two main packages: the
	<code>com.jacob.com.*</code>> package and the
	<code>com.jacob.activeX</code> package. The
	<code>com.jacob.com.*</code> package contains classes map very closely to the com dispatch model with the
	<code>com.jacob.com.Dispatch</code> acting as the primary communication class. Dispatch operate as a function library with a set of static methods that map
	very closely to the C++ Dispatch APIs provided to the COM layer.
	<p></p>
	<code>com.jacob.activex.ActiveXComponent</code> can be used in place of Dispatch to provide a more object like API. The only exception to this guideline is that the
	<code>ActiveXComponent</code> class is always used to make the initial connection to the target dll/COM component.

	<hr>
	<H2> Considerations when doing server side automation of office </h2>

	Most office and many windows client type applications are not written to be used in high volume or multi-threaded server
	environment. There is a
	<a href="http://support.microsoft.com/kb/257757/">
		support note </a>
	on the Microsoft web site that discusses some of the issues.
	<p></p>
	<hr>
	<H2> Determining the API of the target application </h2>
	Section not yet written.

	<hr>
	<h2> The Jacob DLL </h2>

	Jacob.jar relies on a DLL file that it loads off of the library path or classpath. This means that you must either copy the
	appropriate jacob dll into your path or use VM options to add directory holding jacob dll to the path. Prior to 1.14M6,
	the jacob DLL name was always "jacob.dll". This made it hard to verify jacob was loading the correct dll when multiple copies
	of jacob were installed on a single system. It also was confusing on 64 bit systems where the 32 bit and 64 bit dlls have
	the same tames. Starting in 1.14M6, Jacob's library loader selects a dll with the appropriate name based on the jacob release
	and platform. The dll naming convention is:
	<BR>
	<code>jacob&lt;platform&gt;.&lt;version.&gt;.dll</code>

	<h3>Classloader issues</h3>
	The code is written so that the jacob.dll is only loaded one time per classloader. This works fine in the standard application
	but can cause problems if jacob.jar is loaded from more than one class loader. This can happen in the situation where multiple
	jacob dependent web applications run in the same container like a web server or JWS runtime. In the case of a web server,
	Jacob is normally put in the application specific WEB-INF/lib directory. This is the "right" way to do it and works in most
	situations. But, if Jacob is put in the WEB-INF/lib directory of each application's war file for more than one application
	then a problem occurs. In this situation, the web server uses a different classloader for each application. This means that
	each application will attempt to load the jacob.dll and errors are generated. The only way around this at this time (1.11)
	is to put the jacob.jar in the common/lib because that classloader is inherited by all of the applications so the DLLs will
	only get loaded once. This problem is described in SF 1645463 and should be fixed in some future release, fix method and
	time not yet determined.

	<hr>
	<h2>Microsoft Visual C++ library dependencies.</h2>
	<p>
		Jacob 1.15 is build with VC++ 2005 statically linked into the DLL. This removes the need for a separate msvcr80.dll installation.
	</p>
	<p>
		Jacob 1.13 is built with VC++ 2005 that creates a dependency on msvcr80.dll. Windows XP and later seem to already include
		the necessary components. NT/2000 and Server/2003 require that you download the Visual C 2005 redistributable package,
		vcredist_x86.exe from the Microsoft web site. Microsoft has a download available that supplies the necessary components.
		It is distributed as a redistributable package.
	</p>
	<p>
		If you see the following message then you probably don't have the right C++ libraries.
	</p>
	<pre>
	Exception in thread "main" java.lang.UnsatisfiedLinkError: C:\apps\...\jacob.dll: This application has 
	failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem 
</pre>
<A href="http://www.microsoft.com/downloads/details.aspx?familyid=200B2FD9-AE1A-4A14-984D-389C36F85647&displaylang=en">
Visual C redistributable installer SP1</A>

	<p></p>
	<hr>
	<h2>Jacob Command Line Settings</h2>
	This library supports several different command line options:
	<table border=1>
		<tr>
			<td colspan=3>
				<h3>dll path location and dll name customization</h3>
			</td>
		</tr>
		<tr>
			<td>&nbsp;&nbsp;&nbsp;</td>
			<td valign="top">
				<h4>java.library.path</h4>
			</td>
			<td>
				Standard Java property used to add the location of the jacob dll to the JVM's library path. (Added 1.11)
				<p></p>
				Example:
				<code>-Djava.library.path=d:/jacob/release/x86</code>
			</td>
		</tr>

		<tr>
			<td>&nbsp;&nbsp;&nbsp;</td>
			<td valign="top">
				<h4>jacob.dll.name</h4>
			</td>
			<td>
				Override the standard DLL name with a custom one. This stops jacob from using its 32bit/64bit detection and dll rendezvous
				logic. Sometimes used when Jacob is bundled with another application and the application wishes to tie the jacob dll
				version number to the application version number. (Added 1.14M7)
				<p></p>
				Example:
				<code>-Djacob.dll.name=MyFunkyDllName.dll</code>
			</td>
		</tr>

		<tr>
			<td>&nbsp;&nbsp;&nbsp;</td>
			<td valign="top">
				<h4>jacob.dll.name.x86 & jacob.dll.name.x64</h4>
			</td>
			<td>
				Override the standard 32 bit DLL name with custom ones. Sometimes used when Jacob is bundled with another application and
				the application wishes to tie the jacob dll version number to the application version number. (Added 1.14M7)
				<p></p>
				Example to override 32 bit dll name:
				<code>-Djacob.dll.name.x86=MyFunkyDllName-32bit.dll</code>
			</td>
		</tr>

		<tr>
			<td colspan=3>
				<h3>Memory Management</h3>
			</td>
		</tr>
		<tr>
			<td>&nbsp;&nbsp;&nbsp;</td>
			<td valign="top">
				<h4>com.jacob.autogc </h4>
			</td>
			<td>
				Determines if automatic garbage collection is enabled. This is the only way to free up objects created in event callbacks.
				Automatic garbage collection , based on Java gc rules, garbage collection can be enabled via the
				<code>com.java.autogc</code> command line option.
				<em>This feature was added in release 1.9 is not fully debugged. </em>
				<p></p>
				There are real reasons for managing the lifetime of JacobObjects on a per thread basis. Jacob normally manages the the com/Java
				object lifetime as described in the
				<a href="JacobComLifetime.html">JacobComLifetime.html</a> document. Some users have run into situations where they wish to try and let the Java GC lifetime
				manage the lifetime of objects. This seems to usually be tied to long running threads or to objects created as part of
				event callbacks. Code was added to let users try and let the JVM manage the object life cycles even though the
				<a href="JacobComLifetime.html">JacobComLifetime.html</a> document says this is a bad idea. Added 1.9.
				<p></p>

				This value is cached at startup and cannot be changed on-the-fly via
				<code>System.setProperty();</code>
				<p></p>
				The default value is
				<em>false</em>
				<p></p>
				Example:
				<code>-Dcom.jacob.autogc=false</code>

			</td>
		</tr>

		<tr>
			<td>&nbsp;&nbsp;&nbsp;</td>
			<td valign="top">
				<h4>com.jacob.includeAllClassesInROT</h4>
			</td>
			<td>
				Acts as master switch for and &ltclass_name&gt.PutInROT. This property determines if the (experimental) PutInROT property
				is even checked. It was added in version 1.15 because the property check in PutInROT brok applets because they are not
				allowed to check system properties at run time. com.jacob.includeAllClassesInROT is checked at class initialization which
				is allowed.
				<p>The default value of this flag is
					<i>true</i> which matches all behavior prior to 1.13 and the default behavior for 1.13 on</p>
				<p>Setting this flag to false causes Jacob to check the and &lt;class_name&gt;.PutInROT property for every Jacob object
					that is created.</p>
			</td>
		</tr>
		<tr>
			<td>&nbsp;&nbsp;&nbsp;</td>
			<td valign="top">
				<h4>&ltclass_name&gt.PutInROT</h4>
			</td>
			<td>
				Lets a program specify that instances of certain classes are to not be inserted into the ROT. This experimental (1.13) feature
				provides a mechanism for freeing VariantViaEvent objects that are created in Event threads. There is normally no way
				to free those objects because the thread terminates outside of any normally MTA/STA Startup/Teardown code. Each event
				occurs in a new thread and creates a new ROT entry so they grow without bounds.
				<p></p>
				This option may cause VM crashes in certain situations where windows memory is freed outside of the thread it was created
				in but empirical evidence shows there are situations where this great reduces the long running memory footprint of applications
				that process a lot of events.
				<em>This function is still experimental</em>. The functionality was added 1.13. Some of this overlaps the experimental
				<code>com.jacob.autogc</code> introduced in 1.9. See the ROT.java test program for an example of the effects of this option.
				<p> </p>
				This value is checked every time and can be changed on-the-fly via
				<code>System.setProperty();</code>
				<p> </p>

				Example:
				<code>System.setProperty("com.jacob.com.VariantViaVariant.PutInROT","false");</code>
				<BR> Example:
				<code>-Dcom.jacob.com.VariantViaVariant.PutInROT=false</code>
			</td>
		</tr>

		<tr>
			<td colspan=3>
				<h3>Debugging and Troubleshooting</h3>
			</td>
		</tr>
		<tr>
			<td>&nbsp;&nbsp;&nbsp;</td>
			<td valign="top">
				<h4>com.jacob.debug</h4>
			</td>
			<td>
				Determines if debug output is enabled to standard out.
				<p> </p>
				This value is cached at startup and cannot be changed on-the-fly via
				<code>System.setProperty();</code>
				<p></p>
				The default value is
				<strong>false</strong>
				<p></p>

				Example:
				<code>-Dcom.jacob.debug=false</code>
			</td>
			<tr>

				<tr>
					<td>&nbsp;&nbsp;&nbsp;</td>
					<td valign="top">

						<h4>-XCheck:jni</h4>
					</td>
					<td>
						This turns on additional JVM checking for JNI issues. This is not an actual JACOB system property but a property used by
						the JVM.
						<p></p>
						The default is "no additional checking" Example:
						<code>-XCheck:jni</code>
					</td>
				</tr>
	</table>

	<hr>
	<h2>Finding the DLL version using windows command line</h2>
	The jacob.dll file includes the jacob release number in the version field. Run the following from the command prompt
	<code>dumpbin /version jacob.dll</code> . The dll version number is stored in the "image version" field of the "OPTIONAL HEADER VALUES" section. This information
	from
	<a href="http://msdn2.microsoft.com/en-gb/library/h88b7dc8(VS.71).aspx">
		The Microsoft msdn web site</a>

	<hr>
	<h2>Unit Tests</h2>
	Jacob must know the location of the DLL when running the unit tests in Eclipse. The simplest way to do this is to add the
	dll path to the unit as a VM argument. The argument should be specified based on where you installed the jacob source package.
	If you have jacob unpacked in c:/dev/jacob and built using build.xml, then the vm arguments would be:
	<br>
	<code>-Djava.library.path=c:/dev/jacob/release/x86</code> .

	<p></p>
	Last Modified 4/2008 1.15

</BODY>

</HTML>