Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<table class="wysiwyg-macro" data-macro-name="excerpt" data-macro-parameters="atlassian-macro-output-type=BLOCK|hidden=true" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2V4Y2VycHQ6aGlkZGVuPXRydWV8YXRsYXNzaWFuLW1hY3JvLW91dHB1dC10eXBlPUJMT0NLfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">framework for Groovy-based WinNT (Windows) Services </td></tr></table>

<h1>Introduction</h1>

Gosh provides an alternate way to run command-line Groovy scripts, as well as a simplified way to write Windows Services (WinNT Services) using Groovy.  Gosh treats scripts the same, whether they are run from the command-line or as a service (including bindings).  You can debug a service by running it from the command-line, and you can also run standard command-line Groovy scripts.  There is very little difference between a Groovy script that is intended to be run as a Windows Service and any other Groovy script.

Gosh uses <a href="http://javaservice.objectweb.org">JavaService</a> to do the &quot;heavy lifting&quot; of running a Windows Service.  Gosh provides the framework that integrates command-line and service calls with Groovy, and a utility to configure JavaService.  The end result is something that is a lot easier to develop with, and ultimately a lot easier to maintain, than Windows Services based on pure Java using JavaService.

This project has been under development since the middle of 2007, but it still should be considered beta software.  Some of the details documented here are likely to change over time.  We will, of course, attempt to maintain backward-compatibility as much as possible going forward.  As of this writing, the following items still need to be addressed (these will be documented in Jira eventually):
<ul>
	<li>Need an installer.  Manual setup is still a little more complex than I would like.</li>
	<li>Should use a native runner for command-line.  Currently uses a batch file.</li>
	<li>Setting up a new Windows Service requires a batch file.  Should support either a GUI or Groovy script.</li>
	<li>Classloader structure needs peer review (has proven to work well in testing).</li>
	<li>Dynamic-loading design (including folder structure conventions) needs peer review. Folder structure may still change.</li>
	<li>Dynamic loading of DLLs is still experimental at this point - has not been proven in non-sun JVMs.</li>
	<li>Better support for advanced logging.  Currently only supports simple stdout and stderr capture to file.</li>
	<li>Gosh uses an older version of JavaService.exe to run Windows Services.  Needs to be updated and tested. Proven stable through Java 6u3.</li>
	<li>Need to take a look at JavaServiceWrapper from TanukiSoftware as a possible replacement for JavaService, since it seems to have more features and also supports Unix daemons.</li>
	<li>Need to find a new name for the project.  Can anyone do better than &quot;Gosh?&quot; 
<table class="wysiwyg-macro" data-macro-name="warning" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3dhcm5pbmd9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
When installed, Gosh takes over as the default command-line runner for Groovy.  This may break existing code.</td></tr></table></li>
</ul>

<h1>Requirements</h1>

The following is required to run Gosh:
<ul>
	<li>32-bit Windows/Java (x86 architecture) - x64 and IA-64 architectures are not supported</li>
	<li>Java 1.5 or higher</li>
	<li>Groovy 1.5 or higher (included in download)</li>
</ul>

<h1>Installation</h1>

Download the project archive and extract the files.
<ul>
	<li><img class="emoticon emoticon-thumbs-up" data-emoticon-name="thumbs-up" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/thumbs_up.png" alt="(thumbs up)" title="(thumbs up)" /> <a class="confluence-link unresolved" data-filename="gosh-0.1.zip" data-linked-resource-default-alias="gosh-0.1.zip" href="#">gosh-0.1.zip</a> Build 3 (1/3/2008) - Complete build including binaries, source, documentation, and examples.</li>
</ul>

Follow the installation instructions in the .\docs\Groovy Gosh Users Guide.pdf file.

<h1>Building from Source</h1>

Everything you need (except for ant) to build Gosh is included in the download.  Navigate to .\gosh\build and run make.bat.

<h1>Project Structure</h1>

The Gosh project structure is designed to accommodate complex projects.  This may include projects containing multiple JAR libraries and JNI DLLs, where different versions of the same library may exist on one machine.  Gosh also supports convenient programmable runtime configuration using - drumroll please - a Groovy script.

One of the key differences between Gosh and the Groovy command-line tools is the emphasis on local, dynamic (runtime) project configuration.  The Gosh project model follows a convention similar to what you would see in an application server, like a Tomcat web application.  The standard Groovy command-line tools use a global configuration file that applies to all scripts.  Although these tools support dynamically changing the classpath, the support is not obvious and somewhat awkward.

Conversely, in Gosh, there is no global configuration at all.  JAR files (and also DLLs) are local to the project, and are loaded dynamically.  Gosh also supports a local configuration script, written in Groovy, that lets you conditionally define external dependencies.  This makes it easy to use different library versions in different projects on the same machine, something which Groovy isn't particularly good at at them moment.  It also makes it almost foolproof to distribute an entire Groovy-based application to different machines (xcopy or zip the project).

Note that you can run multiple scripts from a single Gosh project.  That includes Windows Services.  So you can define, for example, 5 Windows Services and 20 utility scripts in the same project, all using the same set of JAR files and DLLs.

A Gosh project consists of a root folder containing the following:
<ul>
	<li>Uncompiled Groovy scripts, class files, properties files, and other resources.   </li>
	<li>(optional) A .\GROOVY-INF folder, containing any of the following:
	<ul>
		<li>(optional) A .\lib folder containing JAR files.  These will automatically be added to the classloader.</li>
		<li>(optional) A .\bin folder containing additional Windows *.DLL files.  This path is added to the beginning of the java.library.path, so DLLs in this folder override other DLLs on the local machine.</li>
		<li>(optional) A .\config.groovy script.  This lets you do any additional configuration, like loading external JAR files or setting up logging.</li>
	</ul>
	</li>
</ul>

When you run a Groovy script using Gosh, this is what happens:
<ol>
	<li>Gosh &quot;discovers&quot; the project root folder.  Gosh searches upwards from the current folder, looking for a .\GROOVY-INF folder.  The project root is handled by a single instance of GroovyClassLoader.
	<ol>
		<li>If it is found, the folder containing it becomes the project root.  This affects the assumed package hierarchy of the project.</li>
		<li>If it is not found, the folder containing the script is assumed to be the project root.  Note that this means you can't reliably run Groovy scripts from within packages unless you define .\GROOVY-INF!</li>
	</ol>
	</li>
	<li>If it exists, Gosh loads all the JAR files in .\GROOVY-INF\lib into the system classloader.</li>
	<li>If it exists, Gosh adds the .\GROOVY-INF\bin folder to the java.library.path.</li>
	<li>If it exists, Gosh runs the .\GROOVY-INF\config.groovy script (config.groovy is compiled and cached, so this step actually costs very little).</li>
	<li>Finally, Gosh runs your script.
 </li>
</ol>

Although it looks like a lot is going on here, the logic is actually very streamlined and fast.  We've taken great pains to minimize the startup time, and the performance is generally acceptable.

<h1>Configuring a Windows Service</h1>

You can initially configure a Windows Service using a simple DOS batch file.  Additional configuration is accomplished using Windows administration tools and by directly editing the Windows Registry. The tools are a little crude still, but none of this is very difficult.  The documentation here should give you a clear understanding of what is necessary to configure and maintain a Gosh-based Windows Service.

<h2>1. Initial Configuration: DOS Batch File</h2>

To create (or recreate) a Windows Service, you will need to define a batch file. The batch file will call another batch file, goshservice.bat, with a set of parameters, as in the code example below.  Goshservice.bat wraps the call to JavaService.exe, which requires relatively complex command line syntax. 
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
SET JAVASERVICE_STUB="C:\myapp\bin\MyService.exe"
SET SERVICE_NAME="My Service"
SET GROOVY_SCRIPT="C:\myapp\MyService.groovy"
SET LOGS_FOLDER="C:\myapp\logs\myservice"

C:\apps\gosh\javaservice\goshservice.bat %JAVASERVICE_STUB% %SERVICE_NAME% %GROOVY_SCRIPT% %LOGS_FOLDER%
</pre></td></tr></table>
The parameters you pass to goshservice.bat are defined as follows:
<table class="confluenceTable"><tbody>
<tr>
<th class="confluenceTh"> Parameter </th>
<th class="confluenceTh"> Description </th>
</tr>
<tr>
<td class="confluenceTd"> JAVASERVICE_STUB </td>
<td class="confluenceTd"> Each service needs a renamed copy of JavaService.exe to function. The batch file makes a copy for you, in the location you specify, and uses it to run the service. </td>
</tr>
<tr>
<td class="confluenceTd"> SERVICE_NAME </td>
<td class="confluenceTd"> The name of the service. Must be unique. </td>
</tr>
<tr>
<td class="confluenceTd"> GROOVY_SCRIPT </td>
<td class="confluenceTd"> The groovy script to run as a service. </td>
</tr>
<tr>
<td class="confluenceTd"> LOGS_FOLDER </td>
<td class="confluenceTd"> Standard out and standard err streams will be written to this folder, as files. Note that each service needs a unique folder! </td>
</tr>
</tbody></table>

After you run your batch file, the new service will be accessible for additional configuration from the Windows Services tool.  You can rerun the batch file with different parameters, but remember that you will have to redo the manual configuration steps each time.

<h2>2. Additional Configuration: Windows Tools</h2>

Most Windows Services require some additional setup.  Open the Services tool to finish configuring the service.
<ul>
	<li>start →  Settings → Control Panel → Administrative Tools → Services</li>
</ul>

At a very minimum, you should verify the configuration settings for the following items:
<ul>
	<li>Description - A description of the service.</li>
	<li>Startup Type - Manual or Automatic?</li>
	<li>Log On - The account determines what rights the service has.</li>
</ul>

Once you are done, you can start the service.

<h2>3. Advanced Configuration: The Windows Registry</h2>

Windows stores information about how to run services in the registry.  If you want to play around with some of the service settings, and you are comfortable working directly with RegEdit.exe, you can save yourself some time and effort over recreating and reconfiguring the service each time.  Note that when you change a registry setting, you will have to restart the service for it to become effective.

The following figure shows typical registry settings for the Gosh Sample Service, included in the sample project. You may notice a number of familiar parameters, such as the classpath and the maximum heap size.  These can all be edited, and it is pretty obvious what each one means.

<img class="confluence-embedded-image" src="/download/attachments/230400689/service_params.jpg?version=1&amp;modificationDate=1368953024989" data-image-src="/download/attachments/230400689/service_params.jpg?version=1&amp;modificationDate=1368953024989" data-linked-resource-id="230565145" data-linked-resource-type="attachment" data-linked-resource-default-alias="service_params.jpg" data-base-url="http://docs.codehaus.org" data-linked-resource-container-id="230400689" title="null > service_params.jpg">

<h1>Writing a Service</h1>

At this point, you are probably wondering what the difference is between a regular Groovy script and Groovy script that runs as a Windows Service.

There is a difference.  A Groovy script does a job, and when it is finished, it ends.  With a Windows Service, the program doesn't end until Windows asks it to.  You can implement this - very simply - by creating a loop that checks a flag to exit.
 
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
while(!service.shutdownRequested)
{
 doSomethingServicey()
 service.sleep 5000 //Wait 5 seconds.
}
</pre></td></tr></table>
That is really all there is to it. The service instance is one of the bindings. service.shutdownRequested returns true when Windows has requested that the service be shutdown. service.sleep is a variation on Thread.sleep() that returns immediately if the service has been requested to shut down.

<h1>Examples</h1>

There are several examples in the .\gosh\sample project, included in the build.

The winntservice example implements a complete Windows Service, ready to install and run.  To use:
<ul>
	<li>Run installsampleservice.bat from a command-line.</li>
	<li>Using the Services tool, start the service.</li>
	<li>Check the log files to verify that the service is running.</li>
</ul>

There are also a few command-line examples in the same project.

<h1>Bindings</h1>

Gosh automatically creates a number of bindings.  All of these are available to your script as variables, both when run as a service and when run from the command-line.
<table class="confluenceTable"><tbody>
<tr>
<th class="confluenceTh"> Name </th>
<th class="confluenceTh"> Type </th>
<th class="confluenceTh"> Description </th>
</tr>
<tr>
<td class="confluenceTd"> args </td>
<td class="confluenceTd"> List </td>
<td class="confluenceTd"> When run from the command-line, this contains the command-line arguments. When run as a service, this is an empty list. Gosh does not support passing parameters to a service. </td>
</tr>
<tr>
<td class="confluenceTd"> service </td>
<td class="confluenceTd"> ServiceRunner </td>
<td class="confluenceTd"> Provides state information about the service. When running from a command line, the state information never changes, so you have to shut down the process manually. </td>
</tr>
<tr>
<td class="confluenceTd"> systemClassLoader </td>
<td class="confluenceTd"> GoshClassLoader </td>
<td class="confluenceTd"> The Java system classloader. This classloader allows you add add JAR files and new classpaths at runtime. </td>
</tr>
<tr>
<td class="confluenceTd"> groovyClassLoader </td>
<td class="confluenceTd"> GroovyClassLoader </td>
<td class="confluenceTd"> The Groovy classloader. Note that the parent of the groovyClassLoader is the systemClassLoader. </td>
</tr>
<tr>
<td class="confluenceTd"> fs </td>
<td class="confluenceTd"> FileSystem </td>
<td class="confluenceTd"> Supports finding the root path of your project, creating files from the root of your project (rather than the current folder) using relative paths, and changing the java.library.path, among other things. </td>
</tr>
<tr>
<td class="confluenceTd"> scriptFile </td>
<td class="confluenceTd"> File </td>
<td class="confluenceTd"> The canonical path to the initial Groovy script. </td>
</tr>
</tbody></table>

<h1>Classloader Architecture</h1>

The classloader architecture in Gosh differs somewhat from the architecture found in other the other command-line runners for Groovy.  Gosh replaces the RootClassLoader with the GoshClassLoader, which is a very simple override of UrlClassLoader.

Gosh is broken into two JAR files. The first, dasboot.jar, contains the minimal number of classes to boot Gosh.  This includes the main entry class, the GoshClassLoader, and a small number of supporting classes.  Once dasboot.jar is loaded, the system classloader gets set to an instance of GoshClassLoader, and all the other class libraries, including gosh.jar, are added to it.

Once that is done, Gosh creates a GroovyClassLoader, which is a child of the system classloader.  This classloader is pointed to the root folder of the project, where it interprets uncompiled Groovy scripts.

In all cases, we have attempted to use the simplest, tightest classloader structure that works.  This results in optimal loading and execution times.

<h1>Limitations</h1>

The following are known limitations of Gosh: 
<ul>
	<li>You can't typically use this to bootstrap complex application servers, like Tomcat and JBoss, due to the modified classloader structure and potential conflicts with Groovy JAR library dependencies.  If anyone has success doing this, please contact me.</li>
</ul>