Overview

GigaSpaces .NET API framework allows .NET users to perform space operations using .NET business objects. The .NET objects are transformed into space Entries, transparently allowing the .NET application to write, read, take, and receive notifications. This section describes the space operations you can perform.

Connecting to Space

To connect to the space, you should first get the space proxy using the JsSpaceProxyFactory class:

ISpaceProxy proxy = JsSpaceProxyFactory.Instance.FindSpace(spaceUrl);

The Space URL can represent remote, embedded, or clustered in a single space proxy. For more details, refer to the Space URL section.

Introducing Class to Space

The ISpaceProxy.Snapshot() method should be used to explicitly to introduce .NET business classes to the space.

proxy.Snapshot(new Person());

If the space stores the same class with different attributes or types, an UnusableEntryException is thrown.

Writing Object to Space

A write operation places a copy of an Entry into the given JavaSpaces service. The object instance passed to the write is not affected by the operation. Each write operation places a new Entry into the specified space, even if the same Entry object is used in more than one write.

Writing an Entry into the space might generate notification events to registered objects (see below).

When writing your objects to the space, construct the object as usual, and use the ISpaceProxy.Write operation:

The Person object:

namespace Examples
{
class Person
{
public string m_UserId;
public string m_Name;
public int m_Age;
public float m_Weight;

public string UserId
{
get { return m_UserId; }
set { m_UserId = value; }
}

public string Name
{
get { return m_Name; }
set { m_Name = value; }
}

public int Age
{
get { return m_Age; }
set { m_Age = value; }
}

public float Weight
{
get { return m_Weight; }
set { m_Weight = value; }
}

public Person()
{
}
}
}

Person p = new Person();
p.UserId = "011-1111111";
p.Name = "Kermit the frog";
p.Age = 38;
p.Weight = 200.5F;

ISpaceProxy proxy = JsSpaceProxyFactory.Instance.FindSpace(spaceUrl);
proxy.Write(p);

This call generates a new Entry inside the space.

UpdateModifiers Parameter

The UpdateModifiers modifier is used as a parameter in the ISpaceProxy.Write operation, and includes the following options: PartialUpdate, UpdateOnly, UpdateOrWrite (see About Space Operations), WriteOnly (the same use as in the Java UpdateModifiers class; see Javadoc).

private void UpdateModifiersDemo()
{
ISpaceProxy proxy = SpaceProxyProviderFactory.Instance.FindSpace("/./mySpace");
object objectInstance = new object();

// UpdateModifiers contains values to customize the behaviour of write/update operations.
// For example: in this write operation, if entry already exists in space an EntryAlreadyInSpaceException will be thrown.
proxy.Write(objectInstance, null, long.MaxValue, 0, UpdateModifiers.WriteOnly);
// More info: /docs/JavaDoc6/com/j_spaces/core/client/UpdateModifiers.html
}

Lease

The space provides a mechanism, called leasing, that keeps the space clean and consistent even if applications disconnect before they erase their temporary data. Leasing is supported both for regular write operations and transactions.

Each time an application writes an object to the space, it must specify the lease time – how long it should remain in memory before the space automatically deletes it.

If the information is of a persistent nature, the lease can be set to FOREVER (and the object is never erased). Otherwise, a limited lease time can be set, such as 5 minutes – after this elapses, if the object is still needed, it is the application's responsibility to renew the lease.

Each write invocation returns a Lease object that is lease milliseconds long. If the requested time is longer than the space is willing to grant, you will get a lease with a reduced time. When the lease expires, the Entry is removed from the space.

To explicitly enable this behavior with the .NET API, initialize a .NET proxy with NoWriteLease = false in the space URL (default is false):

string spaceUrl = "jini://*/./mySpace?NoWriteLease=false"

You can then perform the Renew() or Cancel() methods on the Lease.

ILeaseContextleaseContext =
proxy.Write(new Preson("Ben"));
...
leaseContext.Renew(1000);
...
leaseContext.Cancel();

Template Construction

Templates are used with Read, ReadMultiple, ReadIfExists, Take, TakeMultiple, TakeIfExists, AddListener, GetSpaceIterator, Snapshot, Count, and Clear operations.

The template object should include a NullValue indication as part of the object fields, that should be ignored when matching is performed. The simple way to do this is to decorate the class with the [SpaceProperty(NullValue = ...)] attribute with a value that represents null, and have this value as the default value for the field when constructing the object.

For more details, refer to the PONO Class and Field Level Attributes section.

Reading an Entry from Space

To get a specific object copy from the space, you should use the ISpaceProxy.Read operation and provide the relevant template. The template should include field values that you would like to use for matching, and NullValue values for all the rest of the fields.

ISpaceProxy proxy = SpaceProxyProviderFactory.Instance.FindSpace("/./mySpace");
Person pTemplate = new Person();
pTemplate.UserId = "011-1111111";
Person resultRead = proxy.Read<Person>(pTemplate);

When you would like to get a copy of an object that belongs to a specific class type, regardless of its values, construct a template from the relevant class without specifying any values for its fields:

Person pTemplate = new Person();
Person resultRead = proxy.Read<Person>(pTemplate);

ReadModifiers Parameter

The ReadModifiers modifier is used as a parameter in the ISpaceProxy.Read operation, and includes the following options: RepeatableRead, ReadCommitted, DirtyRead, and ExclusiveReadLock - the same use as in the Java ReadModifiers class; see

.

private void ReadModifiersDemo()
{
ISpaceProxy proxy = SpaceProxyProviderFactory.Instance.FindSpace("/./mySpace");
object objectInstance = new object();
// ReadTakeModifiers contains values to customize the behaviour of read/take operations.
// Use proxy.getReadModifiers() and proxy.setReadModifiers() to control the space behaviour.
// For example:
proxy.ReadModifiers = ReadModifiers.DirtyRead;
objectInstance = proxy.Read<object>(new object());
// More info: docs/JavaDoc/com/j_spaces/core/client/ReadModifiers.html
}

Taking an Entry from Space

The Take() method reads an Entry that matches the given template from the space, and removes it.

To take a copy of your object from the space:

ISpaceProxy proxy = SpaceProxyProviderFactory.Instance.FindSpace("/./mySpace");
Person pTemplate = new Person();
pTemplate.user_id = "011-1111111";
Person resultTake = proxy.Take<Person>(pTemplate);

Updating Object in Space

To update an object in the space, you should use the ISpaceProxy.Update operation:

ISpaceProxy proxy = SpaceProxyProviderFactory.Instance.FindSpace("/./mySpace");
Person template = new Person();
template.age = 38;
Person person_read = proxy.Read<Person>(template);
person_read.age = 41;
proxy.Update<Person>(person_read);

Subscribing to Space Events

You can register for notifications via the AddListener method.

The AddListener is generic, meaning it is defined per specific type, where the type given is the name of the PONO you want to define the AddListener for.

For example:

public void NotifyDemo()
{
ISpaceProxy proxy = SpaceProxyProviderFactory.Instance.FindSpace("/./mySpace");

// NotifyDelegator provides a way to receive event notifications.
// More info: docs/JavaDoc/com/j_spaces/core/client/NotifyDelegator.html

// Create a listener:
proxy.DefaultDataEventSession.AddListener<Person>(new Person(), MyNotifyDemoListener.Space_PersonChanged, DataEventType.All);

// This write operation will trigger a notification of type write to occur on listener.
proxy.Write<Person>(new Person());
}

The AddListener includes a listener (a callback method invoked by the space). Furthermore, the object data field is included in the event argument, which holds the PONO that triggered the event.

Example for a .NET listener method:

public class MyNotifyDemoListener
{
public static int Count = 0;
public static void Space_PersonChanged(object sender, SpaceDataEventArgse)
{
long notificationTime = DateTime.Now.Ticks;
Console.WriteLine("MyDelegator.notify started.");
Person p = e.Pono;
System.Threading.Interlocked.Increment(ref Count);
}
public MyNotifyDemoListener()
{
Count = 0;
}
}

For more details, refer to the Session Based Messaging API section.

Transactions

Use the ITransaction interface to create a local transaction:

ITransaction txn = proxy.CreateLocalTransaction();
proxy.Write(person1, txn);
txn.Commit(1000);

To create a Jini transaction, use the ITransactionManager, which creates and manages the distributed Jini transaction:

ITransactionManager jiniTxnManager =
                       proxy.Factory.FindJiniTransactionManager();
txn = jiniTxnManager.Create(proxy.Factory.DefaultLeaseTime);
proxy.Write(person1, txn);
txn.Commit(1000);

For more details on GigaSpaces transactions, refer to the JavaSpaces Transaction Support section.

Committing and Aborting the Jini Transaction

When using the Jini Transaction Manager, you should consider using the ITransaction.Commit(long timeout) and ITransaction.Abort(long timeout) methods.

These return an acknowledgement to the caller application only after the transaction commit or abort operation has been fully completed by all transaction participants, or until the timeout period expired.

When using the ITransaction.Abort() and ITransaction.Commit(), the client gets the acknowledgement immediately after the abort or commit call, without waiting for all transaction participants to be completed. This might lead to inconsistency.

The timeout parameter allows you to choose the maximum amount of time you would like to wait for the transaction to be completed by all participants.

Make sure you do not define a large number (in milliseconds), because one of the transaction participants might hang without returning to the caller. This results in client hang.

This does not occur when using the Local Transaction Manager, because the client gets the acknowledgement for the commit or abort operation only after the space has completed the commit or abort processing.

For more details, refer to:

• http://java.sun.com/products/jini/2.0/doc/api/net/jini/core/transaction/Transaction.html#abort(long)
• http://java.sun.com/products/jini/2.0/doc/api/net/jini/core/transaction/Transaction.html#commit(long)

Batch operations

You can perform batch operations using writeMultiple, readMultiple, takeMultiple, or updateMultiple.

When using writeMultiple or updateMultiple, you should construct an array of objects that you would like to store or update inside the space.

writeMultiple

Person[] persons = new Person[10] ;
for (int i = 0; i < 10; i++)
{
persons[i]= new Person();
persons[i].user_id = "011-1111111_" +i;
persons[i].name = "Kermit the frog" + i;
persons[i].age = 38 ;
persons[i].birthDay = "01/01/1967";
persons[i].height = 6.2 + i;
persons[i].phone = 9783698583L + i;
persons[i].weight = 200.5F + i;
}
Lease[] leases = proxy.writeMultiple(persons, null, LeaseImpl.FOREVER);

updateMultiple

Person templateAge = new Person();
templateAge.age = 38;
persons_read = proxy.readMultiple(templateAge, null, 10000);
proxy.updateMultiple(persons_read, null, new long[10]);

Iterating the Space

You can iterate the space using the GetSpaceIterator method. The GetSpaceIterator method can take a collection of templates as an argument.

object iteratorTemplate = new Person();
ISpaceIteratoriterator = proxy.GetSpaceIterator(iteratorTemplate, IteratorScope.ExistingAndFutureEntries);
foreach (Person person in iterator)
{
Console.WriteLine("Height=" + person.height);
}

Querying the Space

You can query the space using a SQL query. The query should be constructed and passed as the template argument to the Read, Take, ReadMultiple, TakeMultiple, Count, or Clear operations.

Person personTemplate = new Person();
personTemplate.age = 21;
SqlQuery query = new SqlQuery(personTemplate, "age >= ?");
Object[] persons_read = proxy.ReadMultiple<Person>(query, null, 2000);

It is recommended to use a parameter-based query as seen above (?). Using a static value might reduce performance.

Clean Method

To clean all space Entries and notify templates, call the ISpaceProxy.Clean() method.

When the space is persistent using the JDBC Storage Adapter or using an indexed file, data is removed.

proxy.Clean()

Clean(Type type) Method

You can drop a class and all its instances, including its notify templates, using the proxy.Clean(Type type) method:

proxy.Clean(person.GetType());

Clear Method

To remove Entries based on a given template with or without transactions, use the ISpaceProxy.Clear() method:

proxy.Clear(new Person())

Master-Local Space

You can run the master-local topology using a local cache initialized in the .NET API proxy with the useLocalCache and updateMode parameters as part of the space URL:

string spaceUrl = "jini://*/./mySpace?useLocalCache&updateMode=1"

ISpaceProxy proxy = SpaceProxyProviderFactory.Instance.FindSpace(spaceUrl);

For more details, refer to the Master-Local Space section.

Local View Support

You can create a PONO Local View using the IReadOnlySpaceProxy interface.

Construct the PONO local view as follows:

Person template = new Person();
template.name = "Kermit";
View view = new View(template, "name=?");
IReadOnlySpaceProxy localView = proxy.CreateLocalview(view);
int count = localView.Count();

For more details on Local View, refer to the Space Local View section.

Working with Single Space in Cluster

This option is new in GigaSpaces version 6.0.2 and onwards.

When running on a clustered environment, it is sometimes required to create a proxy that is connected directly to a single space in the cluster. Using this type of proxy can become handy when developing SBA workers.

The ISpaceProxy GetSingleProxy() method returns the proxy to the space that the current clustered proxy is connected to.

ISpaceProxy singleProxy = proxy.GetSingleProxy();

If the space is not clustered, the original proxy is returned.