OOPS Consultancy Ltd

Contents

Introduction
Recent Changes
Download
Usage
Examples
Support

Introduction
AntSpaces provides the capability to run Ant against JavaSpaces. This allows you to coordinate Ant tasks via JavaSpaces, pull out work units from a JavaSpace for distributed Ant tasks to work on, and so forth. See the examples to see how AntSpaces allows you to work with JavaSpaces via Ant.

Thanks to Core Developers for the initial suggestion.

Top

Recent Changes
Current version 1.1

See the CHANGES file in the download for a comprehensive list of changes for each version

Since 1.0:

Read and Take can now invoke on objects read/taken from the space.

Since 0.9:

AntSpaces now has simple transaction capabilities.
Write allows lease settings
Read and Take allows timeout settings

Top

Download
Version 1.1 - release 08-Jul-2005

AntSpaces is released under the Apache license. Right-click and choose Save As if your browser doesn't offer you the option.

antspaces.jar the .jar file to use in Ant, including the required all.policy file (see the usage instructions).

antspaces.tar.gz the source code, tests and documents.

Checksums:
antspaces.jar - MD5 ee6840a47beb16b5ba94289712dd93cf
antspaces.tar.gz - MD5  8a9ef1fc87573c2cb95798b51695d413

Additional Requirements:
You will require a Jini 2.0 setup and a working environment. See Jini.org for more details.

Top

How to use
This document assumes a working Jini/JavaSpace environment. No attempt will be made here to describe how to set up such an environment, or to troubleshoot an existing setup.

For a good Jini/JavaSpace tutorial, see Jan Newmarch's Guide to Jini Technologies

Ant needs to run with a suitable security policy file (all.policy is included in the .jar and .tar.gz downloads). To enable this, run ant thus:

export ANT_OPTS=-Djava.security.policy=$HOME/all.policy
ant -buildfile build.xml

amending the path to all.policy as required. If you wish, you can modify the Ant invocation script directly to incorporate this policy file all the time. all.policy simply contains:

grant { 
        permission java.security.AllPermission; 
};

Reference the AntSpaces in your build.xml eg.

<taskdef name="javaspace" classname="com.oopsconsultancy.antspaces.ant.JavaSpaceTask"/>

Reference the javaspace task as part of your build eg.

  <target name="main">
    <javaspace ...>
    ...

The AntSpace task first needs to specify a JavaSpace

<javaspace groups="" timeout="10000" >

which specifies a space belonging to any groups, and a timeout of 10000ms

Parameters

Attribute	Description	Required
groups	specifies a comma-separated set of groups that the space must belong to. If omitted or left blank then LookupDiscovery.ALL_GROUPS will be used	no
timeout	specifies a timeout in ms to be used whilst looking for a space. If omitted then a timout of 'forver' is implied	no
transaction	if set to 'true', specifies that transactions are to be used. You will need a running mahalo instance (or equivalent). Discovery uses the space groups and timeouts settings currently.	no

AntSpace Subtasks

The subtasks all take an net.jini.core.entry.Entry object as an argument - either specifying the entry to be written into the space, or specifying a template to be read/taken or notified on. An entry is specified thus:

  <entry class="net.jini.lookup.entry.Address">
    <field name="country">UK</field>
    <field name="postalCode">SW1A 1AA</field>
  </entry>

and thus you can specify fields in the entry object to either write or match on. Unspecifed fields will be set according to the default constructor of the specified entry object. At the moment only fields of type java.lang.String can be set.

A object previously serialised to disk can be specified thus:

  <entry file="{path to serialised object}"/>

This object must be a serialised net.core.jini.entry.Entry.

The Write subtask writes an entry into the space

    <write>
      <entry class="{classname}">
      ....
    </write>

to specify a new object, or:

    <write>
      <entry file="{path to serialised object}">
    </write>

to specify a serialised object. or

The Read subtask reads an entry from the space. This will hang until a suitable entry appears.

    <read>
      <entry class="{classname}">
      ....
    </read>

The Read subtask can save the read object to disk.

    <read>
      <entry class="{classname}">
      ....
      <save file="{path}"/>
    </read>

The Read subtask can invoke on read entries.

    <read timeout="5000">
      <entry class="com.oopsconsultancy.antspaces.ser.test.TestableSerializable">
        <field name="A"></field>
        <field name="B"></field>
      </entry>

      <invoke>
        <method name="testMethod"/> <!-- no args -->
        <method name="testMethod2">
          <arg type="java.lang.String">ABC</arg>
          <arg/> <!-- null -->
        </method>
      </invoke>
    </read>

Parameters

Attribute	Description	Required
timeout	specifies the take timeout, in ms. If not specified, `Long.MAX_VALUE` is used	no

The Take subtask takes an entry from the space. This will hang until a suitable entry appears (unless ifExists is set).

    <take>
      <entry class="{classname}">
      ....
    </take>

The Take subtask can save the taken object to disk.

    <take>
      <entry class="{classname}">
      ....
      <save file="{path}"/>
    </take>

The Take subtask can invoke on taken entries.

    <take>
      <entry class="com.oopsconsultancy.antspaces.ser.test.TestableSerializable">
        <field name="A"></field>
        <field name="B"></field>
      </entry>

      <invoke>
        <method name="testMethod"/> <!-- no args -->
        <method name="testMethod2">
          <arg type="java.lang.String">ABC</arg>
          <arg/> <!-- null -->
        </method>
      </invoke>
    </take>

Parameters

Attribute	Description	Required
ifExists	if set to true, this task will fail silently if a suitable object doesn't exist	no
timeout	specifies the take timeout, in ms. If not specified, `Long.MAX_VALUE` is used	no

The Notify subtask waits for suitable entries to appear in the space. As each object appears a nominated Ant target is called. Currently Ant targets are called sequentially. No targets will be called in parallel.

    <notify target="compile">
      <entry class="{classname}">
      ....
    </notify>

Attribute	Description	Required
target	specifies the Ant target to call when the nominated object appears in the space	no
lease	specifies the lease, in ms. If not specified, `Lease.FOREVER` is used	no

Top

Examples
The following illustrate some simple examples. Complete example Ant build.xml files are provided with the source code download.

Connecting to a development JavaSpace, and waiting 10s maximum for a successful connection.
```
    <javaspace groups="development" timeout="10000">
    
```

Writing an object to the space.

    <javaspace groups="development" timeout="10000">
      <write>
        <entry class="net.jini.lookup.entry.Address">
          <field name="street">10 Downing St</field>
          <field name="organization">Government</field>
          <field name="locality">London</field>
          <field name="postalCode">SW1A 1AA</field>
          <field name="country">UK</field>
        </entry>
      </write>
    </javaspace>

Writing a previously persisted object to the space.

    <javaspace groups="development" timeout="10000">
      <write>
        <entry file="address.ser"/>
      </write>
    </javaspace>

Reading an object from the space. This gets any address matching the postcode. The object is then saved to disk. If no such object exists, then the read operation will timeout after 5s, and no save operation will occur.

    <javaspace groups="development" timeout="10000">
      <read timeout="5000">
        <entry class="net.jini.lookup.entry.Address">
          <field name="postalCode">SW1A 1AA</field>
        </entry>
        <save file="address.ser"/>
      </read>
    </javaspace>
    <echo>
      Got token. Build progressing
    </echo>

Taking a named object from the space and invoking on it. Note that here we wait for an indefinite period of time (actually Long.MAX_VALUE ms). The object is saved when taken. If the object can't be saved, then the operation will fail and the take will be aborted due to transactions being specified.

    <javaspace groups="development" timeout="10000" transaction="true">
      <take ifExists="true">
        <entry class="net.jini.lookup.entry.Address">
          <field name="postalCode">SW1A 1AA</field>
        </entry>
        <save file="address.ser"/>
        <invoke>
          <method name="execute"/> <-- no arguments -->
        </invoke/>
      </take>
    </javaspace>
    <echo>
      Found suitable address. Build progressing
    </echo>

Waiting for a named object to appear in the space, and calling a publication task for each appearance.

    <target name="main">
      <javaspace groups="development" timeout="10000">
        <notify target="publish">
          <entry class="net.jini.lookup.entry.Name">
            <field name="name">Publish</field>
          </entry>
        </notify>
      </javaspace>
    </target>

    <target name="publish">
      <echo>
        publishing begins...
      </echo>
          .
          .
          .
    </target>

Top

Support
No mailing lists exist yet for AntSpaces. Please mail OOPS Consultancy with queries, bug reports, suggestions etc.

Top

Known Issues
If you get an error similar to:

BUILD FAILED
java.security.AccessControlException: access denied (java.lang.RuntimePermission setIO)
at java.security.AccessControlContext.checkPermission(AccessControlContext.java:269)
at java.security.AccessController.checkPermission(AccessController.java:401)
at java.lang.SecurityManager.checkPermission(SecurityManager.java:524)
   
Then you're not picking up a suitable policy file. See How To Use, section 1.

Top

Contact
AntSpaces is written and maintained by OOPS Consultancy Ltd.. For enquiries see the support info.

Now hosted on