Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 11 Next »

Introduction

Scriptom (scriptom-2.0.zip) combines the elegant "syntactical sugar" of Groovy with the power of the Jacob library (Java COM Bridge). The result is something that looks an awful lot like Windows Scripting Host (WSH) scripting - only it's for Java.  Once installed into Groovy, Scriptom allows you to script ActiveX or COM Windows components from Groovy.

What this means is that you can use Groovy to automate Word or Excel documents, control Internet Explorer, make your PC talk using the Microsoft Speech API, monitor processes with WMI (Windows Management Instrumentation), or browse the Windows Registry using WShell (among many, many other things).  It is also a convenient way to talk to custom VB6 or COM-enabled Microsoft.NET libraries.  All without ever leaving the comforts of Java.

Of course, Scriptom can be used only on Microsoft Windows.

We recommend that you use Scriptom 2.0 rather than Scriptom 1.2. The current version of Scriptom is currently considered beta software. The codebase is considered stable and feature-complete, and we are primarily just finishing up documentation and adding examples at this point. The Jacob project, which provides the engine that drives Scriptom, was started in 1999 and is being used in thousands of production applications worldwide.  Jacob is already a mature, stable library.  The Scriptom project is only a couple of years old, but has matured rapidly. The goal of Scriptom is to provide a library for Groovy that lets you access the full featureset of Jacob - without requiring you to know a bunch of unnecessary details about ActiveX/COM.

The Scriptom team

Installation

Scriptom 2.0 requires Groovy 1.1 and Jacob 1.14. Because of dependencies on Jacob 1.14, Scriptom also requires Java 1.5 or higher.

Download the project archive(s) and extract the files.

  • (tick) scriptom-2.0.zip Build 2 (11/2/2007) - Scriptom JAR file, jacob.dll, Java source code, ANT build script, examples, tests, and utilities.
  • (info) scriptom-2.0-javadoc.zip - JavaDoc for Scriptom and included type-library information.

Install the jar file and DLL file into your project, and optionally install an update from Microsoft:

  1. Add the Scriptom jar file (scriptom-2.0bX.jar) into your Java classpath.  It contains both Scriptom and Jacob class files, so you don't need to include jacob.jar.
  2. Copy jacob.dll to somewhere on your java.library.path. (usually somewhere on the system 'PATH').
  3. Download and install the following update from Microsoft: Visual C redistributable installer SP1 . The Jacob documentation says this is only necessary for Windows Server 2003 and Windows 2000, but we've found that it may also be necessary for Windows XP.

Building from Source

The project archive contains all the Scriptom source files and an ANT build script. However, to save space, jacob.jar and the Groovy JAR files have been omitted from the archive.  The ANT script jarjars jacob.jar into scriptom-2.0bX.jar as part of the build.  JAR files must be added to the project/lib folder.

The latest build requires Groovy 1.1.

The jacob.jar file is part of the Jacob library (Java COM Bridge).  Scriptom requires Jacob version 1.14 or later.

To build the project, run project/build/make.bat

The build process requires Java 1.5 or higher (Java 1.6 recommended) and ANT 1.6.5 or better.

Changes from Scriptom 1.x

Scriptom 2.0 is a substantial upgrade to previous versions of Scriptom, and is not backward compatible.  We hope you will agree that it is worth a little code rework to get all these great new features! 

  • Provides simplified helper methods for dealing with COM apartment threading models.
  • ActiveXProxy name changed to ActiveXObject to match WSH convention.
  • VariantProxy no longer exists (the functionality was refactored into ActiveXObject).
  • Variant values are converted to and from the equivalent Java type; no more calling .value on everything!
  • Supports COM event callbacks using closures.
  • Supports indexed properties, including multiple indexes.
  • Supports typed, multi-dimensional SafeArrays.
  • Supports pass-byref (in/out) values, both in method calls and event handler callbacks.
  • Supports COM enumerable types (so you can use .each, for example).
  • Supports missing arguments (for optional parameters) in method/property calls and events.
  • Includes constant definitions for several popular Windows applications, derived from these type libraries (see JavaDoc):
    • Microsoft Office 2003
      • Word 2003
      • Excel 2003
      • Outlook 2003
    • Microsoft Scripting (i.e., FileSystemObject)
    • Microsoft Speech API
    • Windows Scripting Host (WSH)
    • WbemScripting (WMI - Windows Management Instrumentation)
  • Supports the latest features from Jacob 1.14, including new support for the Decimal data type and 64-bit integers.

Migrating from Previous Versions of Scriptom

Scriptom 2.0 alpha is not backward compatible with previous versions of Scriptom.  To get your scripts running again, do this:

  • Change all references to ActiveXProxy into ActiveXObject.
  • Wrap any code that references an ActiveXObject in Scriptom.withMTA { ... }, which replaces the way Scriptom previously handled COM threading.  
  • Remove all references to .value property references. 
  • Remove any statically typed references to VariantProxy.
  • Support for COM events is greatly improved in this version - and also greatly changed.  Refer to the Events section below for more information.
  • Verify that your project is using the correct version of jacob.dll.

Quick Start

Let's say you want an application that talks. Pure Java implementations aside (this is, after all, a Groovy/COM tutorial), and ignoring the fact that the default voice on pre-Vista machines sounds like Dr. Zoidberg with a sinus infection, you could use the Microsoft Speech API (SAPI) to get the job done.

You start by creating an ActiveXObject with the prog-id for SpVoice. Now you can call any of the methods it supports. By default, SpVoice will block until it is done speaking, but we're going to have it speak asynchronously and wait until it is done.

If you have scripted COM before, you are probably used to using "magic numbers" throughout your code in place of COM constants.  In this code sample, we're using fully-qualified constants instead.

Scriptom includes fully JavaDoc'd constant and interface definitions from a number of commonly used type-libraries, and you can even create your own.  The source code for generating COM type library definitions for Groovy is written in Groovy(smile) , and it's included in the project. It may not seem like a big deal to replace a couple of numbers, but it will be a lot easier in 10 years to find relevant information on SpeechVoiceSpeakFlags.SVSFlagsAsync than on the number 1 (Google returns a little more than 9 billion hits for the number '1', and about 1,000 for 'SpeechVoiceSpeakFlags.SVSFlagsAsync,' including hits on this paragraph).  And besides, the code reads better.

Speaking of interfaces, it turns out that SpVoice supports several.  You can test an ActiveXObject to see if it supports a given interface using .supportsInterface, and you can cast an ActiveXObject to a given interface using .toInterface

This next example displays the COM interfaces that SpVoice supports (within the SAPI library only):





Programmer's Guide 

The Least You Need to Know about COM

how not to crash the JVM or lock your process

COM Data Types in Scriptom

supported types and conversions in Java, VB6, and VB.NET

COM Methods and Properties in Scriptom

calling COM methods and properties from Groovy

Examples

Here is a simple example that uses the Microsoft ScriptControl to evaluate a JScript expression.   This is a very indirect way to add 2 and 2.

There are many, many potential uses for Scriptom - far to many to try to maintain as part of this documentation.   So we've included a whole slew of meaty examples in the project archive for you to play with.  We'd like to encourage you to go look at those examples, run them, and modify them.  And if you come up with an especially interesting example, let us know about it.  We may even include it in a future release! 

Limitations

  • Can't pass SafeArrays byref.  Causes JVM crash.  May need a Jira.
  • Limitations of Jacob need to be explored and discussed.


  • No labels