Generic Access to the Space

The ExternalEntry class (com.j_spaces.core.client.ExternalEntry; see Javadoc) class, an implementation of the net.jini.core.entry.Entry interface, provides special functionality that goes beyond the JavaSpaces specification.

For full details on the com.j_spaces.core.client.ExternalEntry class, see the Javadoc.

Turns Any Class into a Jini Entry

The primary use of the ExternalEntry class is as a wrapper that allows any Java class to be written to a space.

The JavaSpaces specification sets some requirements for classes and objects to be used in a space - Jini Entries must have a default empty constructor, all fields as objects, no private fields, and must implement the Entry interface class. While new code can be written with these requirements in mind, existing classes must be adapted or rewritten before they can be written to a space.

The ExternalEntry solves this problem by creating a JavaSpaces-compatible wrapper that holds the complete meta-data of a class. This allows for any class, even one that does not comply with the requirements of JavaSpaces, to be written to a space as a Jini Entry. An existing information structure can be easily imported into GigaSpaces.
In the same way, ExternalEntry allows creation of template objects that can be used to read instances of entries from a space.

Another option to perform space-based operations without having classes implement the net.jini. core.entry.Entry interface and have public fields, is to use POJOs. For more details, refer to the JavaSpaces POJO section.

Sharing Objects Between Java , C# and C++

When using ExternalEntry with Entry classes your ExternalEntry objects should have their field names/types/values array ordered in alphabetically order based on the field names.

This is important when having Java applications sharing objects with C# and C++ applications.

For example, lets take the following Entry class:

public class MyClass implements Entry
{
	public MyClass(){}
	Public Long a;
	Public String b;
	Public Long c;
}

The corresponding ExternalEntry should be declared in the following way:

ExternalEntry msg = new ExternalEntry ("MyClass", values, new String[]
{"a","b","c"} , new String[]{"java.lang.Long" , "java.lang.String", "java.lang.Long"});

Refers to Objects by Unique Identifiers

ExternalEntry allows locating objects using their Unique ID (UID), as a powerful alternative to the standard methods offered by JavaSpaces. Identifying objects by UID is often faster and more accurate than matching and inheritance mechanism.
ExternalEntry also allows reading/writing multiple objects from different types in a single operation. The objects are identified as an array of UIDs.

For more details, refer to the JavaSpaces UID Support section.

Using the ExternalEntry Class

This section explains how to use ExternalEntry, in combination with other GigaSpaces methods, to read and write objects to a space.

For a complete documentation of the class's fields, methods and constructors, see Javadoc.

All procedures referring to the read operation can also be applied to the take operation.

For easier reference, constructors are numbered in this section according to their order in the code.

To write a new class to the space:

1. Use Constructor #4 to provide the full meta data of the class - name, field names and field values. You can also specify field types, class inheritance, and indexing and replication settings.
2. Use the GigaSpaces write method to write the ExternalEntry data to the space.
3. Check the lease object returned by the write operation to see the UID set by the server for the object. You may use this UID for subsequent access to this object.

To write a new class instance to the space:

1. Use Constructor #3 to provide class name, and field values. You may also specify class inheritance (to identify the class), and indexing and replication settings for the object you intend to write.
2. Use the GigaSpaces write method to write the new class instance to the space.
3. Check the lease object returned by the write operation to see the UID set by the server for the object. It is recommended that you record this identifier for future use.

To read a single object from the space, querying by meta data:

1. Use Constructor #3 to provide meta data by which the object should be identified - class name and field values (with or without wildcards). You may also specify field types and class inheritance, to narrow the search.
2. A template object is created. Call the GigaSpaces read method, passing this template.
3. If the space contains one or more objects that match the meta data you provided, they are returned by the read method.

To read a single object from the space, querying by UID:

1. Use Constructor #1 to provide the UID of the object you want to read.
2. A template object is created. Call the GigaSpaces read method, passing this template.
3. If the space contains an object with the UID you specified, it is returned by the read method.

   All objects written to a space by GigaSpaces have a UID. You can request any object using this procedure, but only if you know its UID.

To read multiple objects from the space, querying by UID:

1. Use Constructor #2 to provide an array of UIDs. Each UID identifies an object you want to read.
2. A template is created. Call the GigaSpaces readMultiple method, passing this template.
3. If the space contains objects matching the UIDs you specified, they are returned by the readMultiple method.

   You may use this procedure to request multiple objects of different types.

Hello World Example

The Hello World sample application demonstrates a simple exchange of objects in a space. It creates a new message Entry object, writes it to the space and then reads a copy of it.

The following figure shows a modified version of this example, which uses ExternalEntry (Constructor #4) to wrap the class Employee.

import com.j_spaces.core.client.SpaceFinder;
import com.j_spaces.core.client.ExternalEntry;
import net.jini.core.lease.Lease;
import net.jini.space.JavaSpace;

public class HelloWorldXE
{

    public static Void main(String[] args)    {

      if ( args.length != 1 )

      {

        System.out.println("Usage: <URL>");
        System.out.println("jini://lookup host/container name/JavaSpaces");
        System.exit(1);
      }
      try
      {

        String[] fields = new String[2];
        String[] types= new String[2];
        Object[] values = new Object[2];

        fields[0] = "id";
        values[0] = "12345";
        fields[Look And Feel - ServiceGrid] = "name";
        values[Look And Feel - ServiceGrid] = "John";
		types[0] = "java.lang.String";
		types[Look And Feel - ServiceGrid] = "java.lang.String";

        ExternalEntry msg = new ExternalEntry ("Employee", values, fields,types);

        JavaSpace space = (JavaSpace)SpaceFinder.find( args[0] );

        Lease ls = space.write(msg, null, Lease.FOREVER);
        ExternalEntry template = new ExternalEntry("Employee", null, null);
        ExternalEntry result = (ExternalEntry )space.read(template, null, Long.MAX_VALUE);
        System.out.println(result.m_FieldsNames[0] + " : " + result.m_FieldsValues[0]);
        ls.cancel();
        System.exit(0);
      }
      catch (Exception e)
      {

        e.printStackTrace();
      }
   }
}

Range Query Example

The following example demonstrates range query using the ExternalEntry. The MatchCodes and the ExternalEntry.setExtendedMatchCodes are using to define lower and upper limits for the range. Make sure your Entry classes include the __getSpaceIndexedFields method to index the appropriate field. The ExternalEntry in this case includes only the field you want to use for the query - i.e. the if field.
The query represented with this example is:

select * from MyEntry where id>=12 and id<=34

The Entry Class:

package com.gigaspaces.example.range;

import net.jini.core.entry.Entry;

public class MyEntry implements Entry
{
	public Integer id;
	public String name;

	public MyEntry()
	{
	}

	public MyEntry(Integer anID, String aName)
	{
		this.id = anID;
		this.name = aName;
	}

 public static String[] __getSpaceIndexedFields()
  {
    String[] indexedFields = { "id" };
    return indexedFields;
  }

	public String toString()
	{
		return "MyEntry [id=" + id + ",name=" + name + "]";
	}
}

The application:

package com.gigaspaces.example.range;

import net.jini.core.entry.Entry;
import net.jini.core.lease.Lease;
import com.j_spaces.core.IJSpace;
import com.j_spaces.core.client.ExternalEntry;
import com.j_spaces.core.client.SpaceFinder;
import com.j_spaces.core.client.TemplateMatchCodes;

public class RangeExample
{

	private static final int	NUM_ENTRIES	= 1000;

	public static void main(String[] args)
	{
		if (args.length != 1)
		{
			System.out.println("Usage: <spaceURL>");
			System.out.println("<protocol>://host:port/containername/spacename");
			System.exit(1);
		}
		try
		{
			// find the space with RMI, the Jini lookup or connect to an
			// embedded
			// instance
			IJSpace space = (IJSpace) SpaceFinder.find(args[0]);
			if (space == null)
			{
				System.out.println("Space not found: " + args[0]);
				System.exit(-1);
			}

			System.out.println("Connected to sapce");

			MyEntry[] entries = new MyEntry[NUM_ENTRIES];

			for (int i = 0; i < NUM_ENTRIES; ++i)
			{
				MyEntry mye = new MyEntry(i, "my entry #" + i);
				entries[i] = mye;
			}

			System.out.println("Going to write " + entries.length + " entries to the sapce");

			space.writeMultiple(entries, null, Lease.FOREVER);

			// Lower limit
			String[] fields = new String[Look And Feel - ServiceGrid];
			Object[] values = new Object[Look And Feel - ServiceGrid];

			fields[0] = "id";
			values[0] = 12;

			ExternalEntry q = new ExternalEntry("com.gigaspaces.rangeexample.MyEntry",
			values,fields);

			// match code
			short[] m = new short[Look And Feel - ServiceGrid];
			m[0] = TemplateMatchCodes.GE;
			q.setExtendedMatchCodes(m);

			// Upper limit
			Object[] range = new Object[Look And Feel - ServiceGrid];
			range[0] = 34;

			q.setRangeValues(range);
			System.out.println("Running query");
			Entry results[] = space.readMultiple(q, null,1000);
			System.out.println("Got " + results.length + ", number of entries back");
			System.out.println("Printing results...");
			for(int i = 0 ; i < results.length ; ++i)
			{
				Entry e = ((ExternalEntry)results[i]).getEntry(space);
				System.out.println(e);
			}

		}
		catch (Exception e)
		{
			e.printStackTrace();
		}

	}
}

Make sure extended match is enabled by including the following in your space schema: <extended-match> <enabled-classes>*</enabled-classes> </extended-match>

More in This Section

• IGSEntry