ActiveX application client programming guidelines

In general, the best way to access Java components is to use the Java language. Because of this, it is recommended that you do as much programming as possible in Java and you use a small simple interface between your COM Automation container (for example, Visual Basic) and Java. This avoids any overhead and performance problems that can occur when moving across the interface between ActiveX and Java.

See these topics for more information about good programming practices for ActiveX application clients:

• Visual Basic guidelines
• CScript and Windows Scripting Host (WSH)
• Active Server Pages guidelines
• J2EE guidelines

Visual Basic guidelines

These guidelines are intended to optimize using the ActiveX to enterprise bean bridge with Visual Basic:

• Launch Visual Basic through launchClientXJB.bat
  If you want to run your Visual Basic application through the Visual Basic debugger, be running the Visual Basic IDE (Integrated Development Environment) within the ActiveX to enterprise bean bridge environment. After your Visual Basic project is created, you can simply launch it from a command-line; for example, launchClientXJB MyAppliation.vbp. Alternatively, you can launch Visual Basic alone in the ActiveX to EJB environment by changing the Visual Basic shortcut on the Windows Start menu so that launchClientXJB.bat precedes the call to VB6.EXE.

• Exit the Visual Basic IDE before debugging programs
  Because the Java virtual machine (JVM) attaches to the running process, exit out of the Visual Basic editor before you debug your program. If you run your program and then exit it within the Visual Basic IDE, the JVM continues to run, and you reattach the same JVM when XJBInit() is called by the debugger. This causes problems if you are trying to update XJBInit() arguments (for example, the classpath), because the changes are not be applied until you restart Visual Basic.

• Store XJB.JClassFactory Globally
  Because the JVM cannot be unloaded or reinitialized, cache the resulting XJB.JClassFactory object as a global variable. The overhead of treating it as a global variable or passing a single reference around is much less than recreating a new XJB.JClassFactory object and calling XJBInit() more than once.

CScript and Windows Scripting Host

The following guideline is intended to help optimize your use of the ActiveX to enterprise bean bridge with CScript and Windows Scripting Host (WSH):

• Launch in ActiveX to EJB environment
  To run VBScript files (in .vbs files), launch the VBScriptfiles in the ActiveX to enterprise bean bridge environment. Here are two ways to launch your script:

    launchClientXJB MyScript.vbs 
    launchClientXJB cscript MyScript.vbs

  The cscript command specifies that your VB script runs inside of the WSH.

Active Server Pages guidelines

These guidelines are intended to help optimize use of the ActiveX to enterprise bean bridge with Active Server Pages (ASP):

• Use the ActiveX to enterprise bean helper functions from Active Server Pages
  Because Active Server Pages typically uses VBScript, the documentation includes some helper functions that you can use in any VBScript environment with minor changes. For more information about these helper functions, see Helper methods for data type conversion. To be able to run outside of the ASP environment, the only change you need to make is to remove or change all references to the Server, Request, Response, Application and Session objects; for example, change Server.CreateObject to CreateObject.

• Set JRE Path Globally in System
  The XJB.JClassFactory must be able to find the Java runtime DLLs when it initializes. In Internet Information Server you cannot specify a path for its processes independently; set the process paths in the system PATH variable. This means that you can only have a single JVM version available on a machine using ASP. Also, remember that after you change the system PATH variable reboot the Internet Information Server machine so that Internet Information Server can see the change.

• Set the system TEMP environment variable
  If the system TEMP environment variable is not set, Internet Information Server stores all temporary files in the WINNT directory. This is usually not a desired behavior.

• Use high isolation or an isolated process
  When using the ActiveX to Java bridge with Active Server Pages, it is recommended that you create your Web application in its own process. This is because you can only load one JVM in a single process and if you want to have more than one application running with different JVM environment options (for example, different classpaths), then you need to have separate processes.

• Use the application Unload button
  When you debug your application, click Unload from the application properties window in the Internet Information Server administrative console. This unloads the process from memory (and thereby unloads the JVM).

• Run one process for each application
  In your ASP environment, only use one ASP application for each J2EE application or JVM environment. If you need separate classpaths or JVM settings, you need to have separate ASP Applications (virtual directories with high isolation or isolated process).

• Store XJB.JClassFactory in application scope
  Because of the one-to-one relationship required between a JVM and a process, and because the JVM can never be detached or shutdown from a process independently, cache the XJB.JClassFactory object at Application scope and call XJBInit() only once.

  Because the ActiveX to enterprise bean bridge employs a free-threaded marshaler, be able to take advantage of the multi-threaded nature of Internet Information Server and ASP. If you choose to reinitialize the XJB.JClassFactory object at Page scope (local variables), then the XJBInit() method can only initialize your local XJB.JClassFactory variable. Therefore, it is more efficient to do the XJBInit() once instead of many times.

• Use VBScript conversion functions
  Because VBScript only supports variant data types, use the CStr(), CByte(), CBool(), CCur(), CInt(), Clng(), CSng() and CDbl() functions to tell the ActiveX to enterprise bean bridge what data type you really mean to use; for example oMyObject.Foo(CDbl(1.234)).

J2EE guidelines

These guidelines are intended to help optimize use of the ActiveX to enterprise bean bridge with J2EE:

• Store client container object globally Because you can only have one JVM for a process, and a single J2EE client container (com.ibm.websphere.client.applicationclient.launchClient) for a JVM, initialize your J2EE client container only once and reuse it. For ASP, store the J2EE client container in an Application level variable and initialize it only once (either on the Application_OnStart() event in global.asa or by checking to see if it IsEmpty()).

  A side effect to storing the client container object globally is that you are unable to change the client container parameters without destroying the object and creating a new one. These parameters include the EAR file, BootstrapHost, classpath, and so on. If you are running a Visual Basic application and you want to change the client container parameters, end the application and restart it. If you are running an Active Server Pages application, first unload the application from Internet Information Server (see "Use the Application Unload Button" under the Active Server Pages guidelines). Then load the Active Server Pages application with the different client container parameters. The first time the Active Server Pages application is loaded, the parameters are set. Because the client container is stored on the Internet Information Server, the parameters are shared by all browser clients that use the Active Server Pages application. Because of this, you cannot connect to different WAS instances with the same Active Server Pages application.

• Reuse custom temp directory for EAR file extraction
  By default, when the client container is launched, it extracts the application's EAR file to your temp directory and then sets up the thread's ClassLoader to use the extracted EAR file directory and JAR files that are included in the client JAR file's manifest. This process is time consuming, and because of some limitations with JVM shutdown through Java Native Interface (JNI) and file locking, these files are not cleaned up.

  Specifically, each time the client container's launch() method is called, it extracts the EAR file to a random directory name in your temporary directory on your hard drive. The current Java thread's class loader is then changed to point to this extracted directory, which in turn locks the files within it. In a normal J2EE client, these files are automatically cleaned up after the application exits. This occurs when the client container's shutdown hook is called (which never happens in the ActiveX to enterprise bean bridge), so the temporary directory is not cleaned up.

  To avoid these problems, you can specify a directory into which the EAR file is extracted. Set the com.ibm.websphere.client.applicationclient.archivedir Java system property before you call the client container's launch() method. If the directory does not exist or is empty, the EAR file is extracted in the normal way. If the EAR file was previously extracted, the directly is reused. This feature is particularly important for server processes (for example, ASP) that stop and restart, which potentially call launchClient() several times.

  To update your EAR file, delete the temporary directory first. Then, the next time the client container object is created, it extracts the new EAR file to the temporary directory. If you do not delete the temporary directory or change the system property value to point to a different temporary directory, the client container reuses the currently extracted EAR file, and your changed EAR file is not used.

  Note: When you specify the com.ibm.websphere.client.applicationclient.archivedir property, make sure that the directory you specify is unique for each EAR file you use. For example, do not point MyEar1.ear and MyEar2.ear to the same directory.

  If you choose not to use this system property, you need to regularly go to your Windows temp directory and delete the WSTMP* subdirectories. Over a relatively short period of time, these subdirectories can waste a very significant amount of space on the hard drive.