script Windows ActiveX and COM components with Groovy

Introduction

Scriptom (scriptom-1.5.zip), an optional Groovy module originally developed by Guillaume Laforge, 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 with VBScript - 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 (compare this to the administrative headaches of getting Java and .NET to talk using Web Services - it's a no brainer).  All this without ever leaving the comfortable Java universe.

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

Scriptom is bundled into the Groovy Windows-Installer, and the most current version can be downloaded from this page (see below). The codebase is considered stable and feature-complete.  The Jacob project - Scriptom's foundation - was started in 1999 and is being used in thousands of production applications worldwide.  Scriptom is only a few years old, but it is already stable and mature because it is built on an existing, best-of-breed platform. 

Scriptom gives you all the COM-scripting power of Jacob, only it is a lot easier.

The Scriptom team

Installation

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

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

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

  1. Add the Scriptom jar file (scriptom-1.5.0bX-XX.jar) into your Java classpath.  It contains both Scriptom and Jacob class files, so you must not include jacob.jar.

    Scriptom contains a full (current) version of the Jacob library. If you are using Jacob directly elsewhere in your project, remove all references to it and use the version built in to Scriptom.

  2. Copy both Scriptom-1.5.0bX-XX.dll files to somewhere on your java.library.path. (usually somewhere on the system 'PATH').

    The Scriptom DLL naming convention allows multiple versions of Scriptom to run on the same machine. However, you can only run a single version of Scriptom JAR in any given project.

  3. To avoid the dreaded java.lang.UnsatisfiedLinkError, download and install one of the following updates from Microsoft: Microsoft Visual C++ 2005 SP1 Redistributable Package (x86)or Microsoft Visual C++ 2005 SP1 Redistributable Package (x64). Scriptom doesn't support the  IA-64 (Itanium) architecture at this time, mainly due to lack of interest. If you are wondering about the different processor architectures, check out the x86-64 wiki. It is usually necessary to install these updates on Windows Server 2003 and Windows 2000, and we've found that it may also be necessary for Windows XP and even Vista.

    A project can only use one version of Scriptom at a time. If you have installed Groovy using the Groovy Windows Installer, you must remove any versions of Scriptom JAR files or replace them with the latest version. A version of Scriptom is installed as part of the Groovy Windows Installer installation.

    Scriptom 1.5 is not supported for Groovy 1.0 and earlier (Scriptom 1.2 is still available). Please contact us if this presents a serious problem for you.

Building from Source

The project archive contains all the Scriptom source files, Java source files from Jacob, and an ANT build script. To save space, the Groovy JAR files have been omitted from the archive.  For a successful compilation, Groovy JAR files must be added to the project/lib folder.

The latest build requires Groovy 1.5.

Scriptom includes source files from Jacob version 1.14.  You don't need to download it from the Jacob project on SourceForge.net.

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 1.5 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! 

Migrating from Previous Versions of Scriptom

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

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.

import org.codehaus.groovy.scriptom.*
import org.codehaus.groovy.scriptom.tlb.sapi.SpeechVoiceSpeakFlags;
import org.codehaus.groovy.scriptom.tlb.sapi.SpeechRunState;

//Definitive proof that you CAN talk and chew gum at the same time.
Scriptom.inApartment
{
  def voice = new ActiveXObject('SAPI.SpVoice')
  voice.Speak 'GROOVY and SCRIPT um make com automation simple, fun, and groovy, man!', SpeechVoiceSpeakFlags.SVSFlagsAsync
  while(voice.Status.RunningState != SpeechRunState.SRSEDone)
  {
    println 'Chew gum...'
    sleep 1000
  }
}
println 'Speaker 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):

import org.codehaus.groovy.scriptom.*;
import org.codehaus.groovy.scriptom.tlb.sapi.SpeechLib;

Scriptom.inApartment
{
  def voice = new ActiveXObject('SAPI.SpVoice')
  SpeechLib.interfaces.each {name, iid -> if(voice.supportsInterface(iid)) println "SpeechLib.$name - $iid"}
}

Programmer's Guide 

The Least You Need to Know about COM

COM Data Types in Scriptom

COM Methods and Properties in Scriptom

Passing Values by Reference (in-out)

COM Events

All About Arrays

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.

import org.codehaus.groovy.scriptom.*

Scriptom.inApartment
{
  def scriptControl = new ActiveXObject("ScriptControl")
  scriptControl.Language = "JScript"
  println scriptControl.Eval('2.0 + 2.0;')
}

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! 

Some additional examples included with Scriptom:

Consuming Visual Basic 6 (VB6) and Visual Basic.NET COM-enabled DLLs.

Articles

Post Scriptom

All known (unresolved) issues and feature requests are listed in the Scriptom Jira database.

Changes to each build are summarized in the Change Log.

Recent builds of Scriptom can be found here. Older versions are archived: