GS == "XAP9NET" || GS == "XAP9" || GS == "XAP9NET")

.Net PONO API Framework

  GigaSpaces 5.X

Documentation Home
Quick Start Guide
Release Notes

Previous release

  Search Here
Searching GigaSpaces Platform 5.X Documentation

                                               

Summary: GigaSpaces JavaSpaces API Plain Old .NET Object support – the PONO.

Overview

GigaSpaces PONO (Plain Old .NET Object) 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 get notifications. This section describes the space operations you can perform, the different class attributes, and the utility classes provided. 

New in GigaSpaces 5.1
GigaSpaces .NET PONO API Framework is supported in GigaSpaces version 5.1 and onwards.
The GigaSpaces .NET PONO API framework does not support the Map API.
Use the /platform:anycpu switch when compiling and running on 64-bit windows machine platforms. Example:

Using GigaSpaces 5.2:

csc.exe /target:exe /platform:anycpu  /out:Release/benchmark.exe /recurse:./*.cs  /reference:
..\..\lib\netrt.dll;..\..\lib\GsSerializer.dll;..\..\lib\gss52.dll

Using GigaSpaces 5.1 and previous versions:

csc.exe /target:exe /platform:anycpu  /out:Release/benchmark.exe /recurse:./*.cs  /reference:
..\..\lib\netrt.dll;..\..\lib\GsSerializer.dll;..\..\lib\gss50.dll
More in this Section
  • The LeaseRenewalManager provides systematic renewal and overall management of a set of leases associated with one or more remote entities on behalf of a local entity. For more details, refer to the Managing Resources Lease section.
  • To build and run a .NET application using the GigaSpaces PONO API, refer to the Building Your First PONO Application section.

API Enhancements – 5.2

The following .NET enhancements have been added in GigaSpaces version 5.2:

  • Performance improvements.
  • Multiple assembly load order.
  • Reduced threads usage when using notifications.
  • JVM Environment settings.
  • Inner classes support.
  • Support for all .NET data types (PODS) – UInt16, Uint32, and Uint64.
  • Complex Objects support using the [serializeable()] attribute.
  • UPDATE_OR_WRITE support for updateMultiple operations.
  • Override uid attribute – a special method was provided to allow the developer to override the uid attribute in runtime.
  • Extended matching using new getTemplateEntry method.
  • LeaseImpl, GSIterator, NotifyDelgator, and SQLQuery PONO API.
  • PONO Local View support.

Environment Settings

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
     <sectionGroup name="userSettings" type="System.Configuration.UserSettingsGroup, System, Version=2.0.0.0,
     Culture=neutral, PublicKeyToken=b77a5c561934e089" >
       <section name="GigaSpaces.Properties.PONO" type="System.Configuration.ClientSettingsSection, System,
       Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
       allowExeDefinition="MachineToLocalUser" requirePermission="false" />
       <section name="GigaSpaces.PONO" type="System.Configuration.ClientSettingsSection, System,
       Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
       allowExeDefinition="MachineToLocalUser" requirePermission="false" />
     </sectionGroup>
  </configSections>
  <userSettings>
    <GigaSpaces.Properties.PONO>
       <setting name="JVMMinSize" serializeAs="String">
           <value>64</value>
            </setting>
            <setting name="JVMMaxSize" serializeAs="String">
                <value>256</value>
            </setting>
            <setting name="JSHOMEDIR" serializeAs="String">
                <value>f:\GigaSpacesEE5.1\</value>
            </setting>
        </GigaSpaces.Properties.PONO>
        <GigaSpaces.PONO>
            <setting name="JVMMinSize" serializeAs="String">
                <value>64</value>
            </setting>
            <setting name="JVMMaxSize" serializeAs="String">
                <value>256</value>
            </setting>
        </GigaSpaces.PONO>
    </userSettings>
</configuration>

STANDARD and DIRECT Mode

You can instruct the system to use the PONO DIRECT mode, as opposed to the PONO STANDARD mode:

  • STANDARD instructs the system to use the PONO regularly.
  • DIRECT instructs the system to use PBS mode to convert between Java and .NET in a faster manner.

By default, GigaSpaces uses STANDARD mode. If you want to switch to DIRECT mode, change the add key element value attribute in the <GigaSpaces Root>\dotnet\lib\GsSerializer.dll.config file from STANDARD to DIRECT. The GsSerializer.dll.config file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="MarshallingMode" value="STANDARD" />
  </appSettings>
</configuration>
You see the <GigaSpaces Root>\dotnet\lib folder only after you have extracted the <GigaSpaces Root>\dotnet\dotnet.zip file.
Do not edit the GsSerializer.dll.config from your <GigaSpaces Root> directory. Either copy it into the execution folder in your development environment, or specifically, if you are using Visual Studio, copy it into App.config and edit it from there.

After specifying one of the modes in the GsSerializer.dll.config file, there is nothing else you need to do – using PONOs is the same with both modes, as specified in the sections below.

New in GigaSpaces 5.2.1
The PONO DIRECT mode is new in GigaSpaces version 5.2.1 and onwards.

Attributes

Attributes are declarative tags that can be used to annotate types or class members, thereby modifying their meaning or customizing their behavior. This descriptive information provided by the attribute is stored as metadata in a .NET assembly, and can be extracted either at design time or at runtime using reflection.

GigaSpaces .NET framework supports attributes to define the space class meta data information.

Below is an example for a .NET business class using attributes:

using GigaSpaces;
using System.Text;

// Marks the class as persistable.
// This is equivalent to calling makeTransient on an ExternalEntry.
[Persist(true)]

// Marks the class as Replicatable.
// This is equivalent to calling setReplicatable on an ExternalEntry.
[Replicate(true)]

public class Person
{
// Key is used to indicate uniqe field value. This field value is used to generate the Entry UID
// Index is used indicate indexed field
[Key , Index]
public string user_id = null;

public string name = null;

// Nullable is used to indicate a value to be considered as null when object used as a template
[Index , Nullable("-1")]
public int age = -1;

public string birthDay = null;

[Index, Nullable("-1")]
public long phone = -1;

[Index, Nullable("-1.0")]
public float weight = -1;

[VersionID]
public int versionid;

// Sets the routing field name to be the first index for partition
[RoutingIndex]
public string RoutingIndex;

[Index, Nullable("-1.0")]
public double height = -1;
public Person(){

}
}
New in GigaSpaces 5.2
The following are new in GigaSpaces version 5.2 and onwards:
  • The Persist and Replicate attributes.
  • The Key attribute auto-generate option.
  • The RoutingIndex attribute – technology preview.

Class-Level Attributes

Fifo Attribute

The [Fifo] attribute instructs GigaSpaces to write the Entry into the space in FIFO mode. This allows notifications and take operations in FIFO mode.  

For more details, refer to the FIFO Support section.

Persist Attribute

The [Persist] attribute persists the PONO under this attribute – saves it in the database.

Replicate Attribute

When running in partial replication mode, the [Replicate] attribute replicates all PONOs under this attribute to a target space or spaces.

Field-Level Attributes

Key Attribute

The [Key] attribute instructs GigaSpaces to use this field value to be the base of the Entry's UID. This field value must include a unique value. When performing update operations, you must have this attribute defined for one of the fields.

You can not use multiple fields with the [Key] attribute.

The [Key] attribute includes an auto-generate option, meaning, defining [Key(true)] instructs the space to automatically generate the PONO's ID (key value).

For example:

{
  // Marks the field to hold the UID of the entry.
  // Specify autoGenerate=true to make GigaSpaces generate a unique UID for 
  // you, and store it in the field.
  [Key(true)]
  public string PersonID;
}
For more details, refer to the JavaSpaces UID Support section.

Index Attribute

The [Index] field attribute instructs the space to index the field data. Indexing speeds up read and take operations using templates the SQLQuery and impacts write and update performance operations.  

When using SQLQuery with bigger/less than conditions, make sure you use extended indexing.
For more details, refer to the Indexing section.
 

Nullable Attribute

The [Nullable] attribute instructs GigaSpaces to ignore this field when performing matching or partial update. 

VersionID Attribute

The [VersionID] attribute instructs GigaSpaces to store the Entry's Version ID into the PONO field. The VersionID field is incremented with every PONO update.

Make sure you place the VersionID field in the extended class, and not in its
base class. This field is not supported when written only in the base class.

RoutingIndex Attribute

The [RoutingIndex] attribute routs the PONO field under this attribute to the relevant space. This is done using hash-based load-balancing.

Technology Preview
The RoutingIndex attribute is a technology preview and is not currently available for production.
The RoutingIndex attribute can be used with the partitioned, replicated, and sync_to_backup schemas, except when working with the CacheLoader/CacheStore. This functionality will be available in future versions.

Space Operations

Getting the Space Proxy

Getting a space proxy is done via the GigaSpace class.

GigaSpace proxy = new GigaSpace(spaceURL);

 

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

Writing an Object to Space

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

Person p = new Person();
p.user_id = "011-1111111";
p.name = "Kermit the frog";
p.age = 38;
p.birthDay = "01/01/1967";
p.height = 6.2;
p.phone = 9783698583L;
p.weight = 200.5F;
proxy.write(p, txn, LeaseImpl.FOREVER);
 
This call generates a new Entry inside the space.

LeaseImpl Parameter

The LeaseImpl defines a certain timeout for the GigaSpace.write and the GigaSpace.update operations. The timeouts you can specify are: ABSOLUTE, ANY, DURATION, and FOREVER (the same use as in the Lease interface; see Javadoc).

class WikiDemo
{
      private void LeaseIMPLDemo()
      {
            GigaSpace space = new GigaSpace("/./myCache");
            object entry = new object(); 

            // LeaseIMPL contains time/duration related values which are commonly used in space operations. 
            // For Example:
            space.write(entry, null, LeaseImpl.FOREVER);
            // More info: http://java.sun.com/products/jini/2.0/doc/api/net/jini/core/lease/Lease.html

      }

New in GigaSpaces 5.2
The LeaseImpl parameter is new in GigaSpaces version 5.2 and onwards.
 

UpdateModifiers Parameter

The UpdateModifiers modifier is used as a parameter in the GigaSpace.write operation, and includes the following options: PARTIAL_UPDATE, UPDATE_ONLY, UPDATE_OR_WRITE (see About Space Operations), WRITE_ONLY (the same use as in the Java UpdateModifiers class; see Javadoc).

private void UpdateModifiersDemo()
      {
            GigaSpace space = new GigaSpace("/./myCache");
            object entry = 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.
            space.write(entry, null, LeaseImpl.FOREVER, 0, GigaSpaces.UpdateModifiers.WRITE_ONLY);
            // More info: /docs/JavaDoc/com/j_spaces/core/client/UpdateModifiers.html
      }
New in GigaSpaces 5.2
The UpdateModifiers parameter is new in GigaSpaces version 5.2 and onwards.

ReadTakeModifiers Parameter

The ReadTakeModifiers modifier is used as a parameter in the GigaSpace.write operation, and includes the following options: DIRTY_READ, and EXCLUSIVE_READ_LOCK (see Exclusive Read Lock) – the same use as in the Java ReadTakeModifiers class; see Javadoc.

private void ReadTakeModifiersDemo()
      {
            GigaSpace space = new GigaSpace("/./myCache");
            object entry = new object(); 

            // ReadTakeModifiers contains values to customize the behaviour of read/take operations.
            // Use space.getReadTakeModifiers() and space.setReadTakeModifiers() to control the space behaviour.
            // For example:
            space.setReadTakeModifiers(GigaSpaces.ReadTakeModifiers.DIRTY_READ);
            entry = space.read(new object(), null, 0);
            // More info: docs/JavaDoc/com/j_spaces/core/client/ReadTakeModifiers.html

      }
New in GigaSpaces 5.2
The ReadTakeModifiers parameter is new in GigaSpaces version 5.2 and onwards.

Template Construction

Templates are used with read, take, notify, NotifyDelegator, readMultiple, takeMultiple, GSIterator.

The template object should include a nullable value 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 [Nullable] attribute with a value that represents null, and have this value as the default value for the field when constructing the object.  

Reading an Entry from the Space

To get a specific object copy from the space, you should use the GigaSpace.read operation and provide the relevant template. The template should have values to the fields you would like to use for matching, and nullable values for all the rest of the fields.

Person pTemplate = new Person();
pTemplate.user_id = "011-1111111";
Person resultRead = (Person)proxy.read(pTemplate, null, LeaseImpl.FOREVER);
 
When you would like to get a copy of an object that is from specific class type regardless its values you should construct a template from the relevant class without specifying any values for its fields:
Person pTemplate = new Person();
Person resultRead = (Person)proxy.read(pTemplate, null, LeaseImpl.FOREVER);
  

Taking an Entry from Space

To get a copy of your object from the space and remove it from the space in one automatic operation:

Person pTemplate = new Person();
pTemplate.user_id = "011-1111111";
Person resultTake = (Person)proxy.Take(pTemplate, null, LeaseImpl.FOREVER);
  

ExternalEntry Usage

When using ExternalEntry as template for the GigaSpace.read/GigaSpace.take operations PONO is returned back.
You may write ExternalEntry as is using the GigaSpace.write operation.

For more details about using the ExternalEntry with the .Net API, refer to: Using ExternalEntry

Introducing Class to Space

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

proxy.snapshot(new Person());

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

Notifications

You can register for notifications via the NotifyDelegator class (com.j_spaces.core.client.NotifyDelegator; see Javadoc).

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

For example:

public void NotifyDelegatorDemo()
      {
            GigaSpace space = new GigaSpace("/./myCache");
            object entry = new object(); 

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

            // Create a listener:
            MyListener listener = new MyListener();
            // Create a notification delegator:
            NotifyDelegator<object> notifyDelegator = new NotifyDelegator<object>(
                  space,            // Space to subscribe to
                  space.Converter.getNullTemplateEntry(new object()), // template to inspect
                  null,                               // Transaction 
                  listener,                           // Event listener
                  LeaseImpl.FOREVER,                  // Lease time
                  null,                               // Handback object
                  false,                                    // FIFO Enabled
                  NotifyModifiers.NOTIFY_ALL);// Notification modifiers 

            // This write operation will trigger a notification of type write to occur on listener.
            space.write(new object(), null, LeaseImpl.FOREVER);
      }

The NotifyDelegator includes a listener (a callback method invoked by the space) which implements INotifyDelegator. Furthermore, the object data field is included in the notify() method, which holds the Entry/PONO that triggered the event.

The INotifyDelegator is also generic, meaning it is defined for a certain type/PONO.

For example:

private class MyListener : INotifyDelegator<object>
      {
            #region INotifyDelegator<object> Members 

            // Old style event:
            public void notify(RemoteEvent theEvent)
            {
                  EntryArrivedRemoteEvent arrivedRemoteEvent = (EntryArrivedRemoteEvent)theEvent;
                  ExternalEntry ee = (ExternalEntry)arrivedRemoteEvent.getEntry(true);
                  Console.WriteLine("Got Notification for " + 
                  getNotifyType(arrivedRemoteEvent.getNotifyType()));
            }
            // New style event:
            public void notify(RemoteEvent theEvent, object data)
            {
                  EntryArrivedRemoteEvent arrivedRemoteEvent = (EntryArrivedRemoteEvent)theEvent;
                  ExternalEntry ee = (ExternalEntry)data(true);
                  Console.WriteLine("Got Notification for " +
                   getNotifyType(arrivedRemoteEvent.getNotifyType()));
            }

            #endregion
            
            private static String getNotifyType(int notifyType)
            {
                  String desc = "";
                  if (NotifyModifiers.isWrite(notifyType)) desc = "Write";
                  if (NotifyModifiers.isTake(notifyType)) desc = "Take";
                  if (NotifyModifiers.isLeaseExpiration(notifyType)) desc = "LeaseExpiration";
                  if (NotifyModifiers.isUpdate(notifyType)) desc = "Update";
                  if (NotifyModifiers.isALL(notifyType)) desc = "ALL";
                  return desc;
            }
      }
For details about the JavaSpaces NotifyDelegator and RemoteEventListener which behave very similarly to the PONO NotifyDelegator and INotifyDelegator, refer to the JavaSpaces Notifications section.
New in GigaSpaces 5.2
The following capabilities are new in GigaSpaces version 5.2 and onwards:
  • Defining the NotifyDelegator per specific type.
  • The INotifyDelegator – in GigaSpaces 5.1 the listener class implements RemoteEventListener and not INotifyDelegator.
  • The notify() method object data field.

Converting ExternalEntry to .NET Object

Converting a .NET ExternalEntry object to a .NET object is done in the following manner:

public void notify(RemoteEvent theEvent)
    {
       EntryArrivedRemoteEvent arrivedRemoteEvent = (EntryArrivedRemoteEvent)theEvent;
       ExternalEntry ee = (ExternalEntry)arrivedRemoteEvent.getEntry(true);
       object obj = proxy.Converter.getObject(ee);
}

Querying the Space

You can query the space using a SQLQuery. The SQLQuery should be constructed and passed as the template argument to the read, take, readMultiple or takeMultiple operations. 

SQLQuery query = new SQLQuery("Person", "height >= 30 and height < 50");
Object [] persons_read = proxy.readMultiple(query, null, 2000);

If you are using GigaSpaces version 5.2.2 and onwards, you can query the space using the SqlQuery wrapper, in the following way:

SqlQuery<Person> query = new SqlQuery<Person>("height >= 30 and height < 50");
Object[] persons_read = proxy.readMultiple(query, null, 2000);
When using SQL queries with .NET, the casing is different. Make sure you use SqlQuery and not SQLQuery as used in Java.

 

Iterating the Space

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

ArrayList templates = new ArrayList();
templates.add(new ExternalEntry("Person", null, null));
GSIterator iterator = new GSIterator(proxy.Space, templates, 1000, true, LeaseImpl.FOREVER);
while (iterator.hasNext())
{
ExternalEntry ee = (ExternalEntry)iterator.next();
Console.WriteLine (proxy.Converter.getObject(ee));
}

It is now possible to convert your object to an ExternalEntry (using the Converter) instead of creating a new ExternalEntry:

private void GSIteratorDemo()
{
     GigaSpace space = new GigaSpace("/./myCache");
     object entry = new object(); 

    // GSIterator provides a way to iterate through entries matching templates one at a time.
   // More info: docs/JavaDoc/com/j_spaces/core/client/GSIterator.html 

  // Example: 

 // Create a list of interesting templates:
 ArrayList templates = new ArrayList();
 templates.add(entry);
 // Create an iterator:
 GSIterator iterator = space.GSIterator(
            templates,              // List of templates to match
            1000,                   // Buffer size
            true,                   // use history
            LeaseImpl.FOREVER);     // Lease time

 // Use a simple loop to iterate through the results one at a time:
 int count = 0;
 while (iterator.hasNext())
 {

       ExternalEntry ee = (ExternalEntry)iterator.next();
       Console.WriteLine((count++) + " " + space.Converter.getObject(ee));
 }
 // Cancel the iterator:
 iterator.cancel();
}
New in GigaSpaces 5.2
Converting your object to an ExternalEntry using the Converter in the GSIterator is new in GigaSpaces version 5.2 and onwards.

If you are using GigaSpaces version 5.2.2 and onwards, you can query the space using the GSIterator wrapper, in the following way:

object template = new Person();
GSIterator iterator = new GSIterator(proxy, template, 1000, true, LeaseImpl.FOREVER);
foreach (Person person in iterator)
{
Console.WriteLine ("Height=" + person.height);
}
Refer to the JavaSpaces Iterator section for more details.

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]);
 

UpdateNoReturn and UpdateMultipleNoReturn

When UpdateMultipleNoReturn() is defined, updateMultiple() is performed without returning the PONO itself. Therefore, the code is freed right after performing the operation. The same is correct for UpdateNoReturn() and update().

For example:

private void UpdateNoReturnDemo()
      {
            GigaSpace space = new GigaSpace("/./myCache");
            object entry = new object(); 

            // updateNoReturn() is equivalent to update(), except it does not return the converted result.
            // The same goes for updateMultipleNoReturn() and updateMultiple().
            // For example:
            space.updateNoReturn(entry, null, LeaseImpl.FOREVER, 0, GigaSpaces.UpdateModifiers.UPDATE_OR_WRITE);
      }
New in GigaSpaces 5.2
The use of UpdateNoReturn() and UpdateMultipleNoReturn() in .NET is new in GigaSpaces version 5.2 and onwards.

Transactions

You can use the Local Transaction Manager or the Distributed Transaction Manager.

Constructing Local Transaction Manager

 
LocalTransactionManager tm = new LocalTransactionManager(proxy.Space);
proxy.write(p, txn, LeaseImpl.FOREVER);
txn.commit(1000);
   

Constructing Distributed Transaction Manager

java.lang.Class txclass = java.lang.Class.forName("net.jini.core.transaction.server.TransactionManager");
TransactionManagerImpl tm = (TransactionManagerImpl)LookupFinder.find(
null, // service name
new java.lang.Class[] { txclass }, // service class name
null, // service attributes
"localhost", // unicast lookup host
null, // lookup groups
10*1000); // timeout 10 seconds

proxy.write(p, txn, LeaseImpl.FOREVER);
txn.commit(1000);
For more details on GigaSpaces transactions, refer to: JavaSpaces Transaction Support.

Committing and Aborting the Jini Transaction

When using the Jini Transaction Manager, you should consider using the Transaction.commit(long waitFor) and Transaction.abort(long waitFor) 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 Transaction.abort() and Transaction.commit(), the client gets the acknowledgement immediately after the abort or commit call, without waiting for all transaction participants to be completed. This may lead to inconsistency. 

The waitFor parameter timeout 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.  

Admin API

Clean Method

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

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

proxy.clean()

Clear Method

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

proxy.clear(new Person() , null)

Setting Security Context

When a space is running in secured mode, the space proxy should have user credentials using the setSecurityContext method:

SecurityContext sc = new SecurityContext("user" , "password");
proxy.Space.setSecurityContext(sc);
 
With each space operation, the space performs the required authorization based on the security roles defined for the user. 
For more details, refer to the Security section.
 

Getting Space Configuration

You can get space configuration using the IRemoteJSpaceAdmin interface:

IRemoteJSpaceAdmin spaceadmin = (IRemoteJSpaceAdmin)proxy.Space.getAdmin();
SpaceConfig config = spaceadmin.getConfig();
 
If the space is running in secured mode, you need to set the security context.

dropClass Method

You may drop a class and all its instances including its notify templates using the dropClass method:

IRemoteJSpaceAdmin spaceadmin = (IRemoteJSpaceAdmin)proxy.Space.getAdmin();
spaceadmin.dropClass(p.GetType().Name); 

Inheritance

GigaSpaces .NET framework supports matching a query based on sub-classes. This means the query potential result-set spans the template class and all its sub-classes. When performing matching with read, take, notify, or GSIterator, the template class sub-classes instances might be returned to the caller. 

For more details, refer to the Inheritance Support section.

Marshaling and Serialization

When the .NET business class instance is stored in the space, its primitive fields are converted into relevant Java data types. See the mapping below: 

C# Primitive Type BCL Type Description
sbyte System.SByte Signed 8-bit value.
byte System.Byte Unsigned 8-bit value.
short System.Int16 Signed 16-bit value.
ushort System.UInt16 Unsigned 16-bit value.
int System.Int32 Signed 32-bit value.
uint System.UInt32 Unsigned 32-bit value.
long System.Int64 Signed 64-bit value.
ulong System.UInt64 Unsigned 64-bit value.
char System.Char 16-bit Unicode character.
float System.Single IEEE 32-bit float.
double System.Double IEEE 64-bit float.
bool System.Boolean A true/false value.
decimal System.Decimal 96-bit signed integer times 100 through 1028 (common for financial calculations where rounding errors can't be tolerated).
object System.Object Base of all types.
string System.String String type. 

.Net to Java Mapping: 

.Net Type Java Data Type
System.Decimal java.math.Decimal
System.Decimal[] java.math.Decimal[]
System.DateTime java.util.Date
System.DateTime[] java.util.Date[]
System.String java.lang.String
System.String[] java.lang.String[]
System.Object java.lang.Object
System.Object[] java.lang.Object[]
System.Int32 java.lang.Integer
System.Int32[] java.lang.Integer[]
System.UInt32 java.lang.Integer
System.UInt32[] java.lang.Integer[]
System.UInt16 java.lang.Short
System.UInt16[] java.lang.Short[]
System.UInt64 java.lang.Long
System.UInt64[] java.lang.Long[]
System.Single java.lang.Float
System.Single[] java.lang.Float[]
System.Double java.lang.Double
System.Double[] java.lang.Double[]
System.Char java.lang.Character
System.Char[] java.lang.Character[]
System.Boolean java.lang.Boolean
System.Boolean[] java.lang.Boolean[]
System.Byte java.lang.Byte
System.Byte[] java.lang.Byte[]
System.Int64 java.lang.Long
System.Int64[] java.lang.Long[]
System.Int16 java.lang.Short
System.Int16[] java.lang.Short[]
In order to have dates translated correctly when moving from .NET to Java and back, create the DateTime object with a DateTimeKind.Utc attribute. For example:
DateTime dt1 = new DateTime(2007, 12, 13, 20, 15, 10, 256, DateTimeKind.Utc);

All non-primitive types are serialized or de-serialized using GigaSpaces .NET serialization technology. When the PONO is stored inside the space, the non-primitive field data is transformed into byte array and stored as one buffer inside the relevant Entry field. When reading or taking an Entry, the buffer is deserialized and materialized to the relevant .Net class. 

Non-primitive Fields Cannot be Used When Performing Matching
You can provide your own serialization or de-serialization implementation, using the
Converter.AddMapping(ObjTypeMarshal typeMarshaler) method.

The ObjTypeMarshal allows you to define the marshalling function that is used when serializing or deserializing non-primitive fields.

Local View Support

The PONO Local View differs from the JavaSpaces Local View.

Construct the PONO local view as follows:

public class Person
        {
            [GigaSpaces.Key]
            public int id;
            public string name;
        } 

        public GigaSpace CreateView(GigaSpace space)
        {
            ExternalEntry ex = space.Converter.getExternalEntry(new Person()); 

            View[] views = new View[2];
            java.util.Properties p = new java.util.Properties();
            p.put("views", (java.lang.ObjectArray)new View[2] { new View(ex, 
            "name='Lior'"), new View(ex, "name='Guy'") }); 

            return new GigaSpace("rmi://localhost/./mySpace", p); 

        }
New in GigaSpaces 5.2
PONO Local View support is new in GigaSpaces version 5.2 and onwards.
For more details on Local View, refer to the Space Local View section.

VM Loader

You can control the VM library loaded into the process using the GigaSpace.loader field. The GigaSpace.loader includes methods that allow you to specify VM properties. 

GigaSpace.loader.InitialHeapSizeInMB = 512;
GigaSpace.loader.MaximumHeapSizeInMB = 1024;
GigaSpace.loader.Load();
GigaSpace space = GigaSpaces.GigaSpace("/./myCache");

Below is a list of attributes and methods of the GigaSpace.loader.

Public Properties:

Attribute Description
Abort The callback for the JVM abortion.
AppendBootClassPath The JVMs append-to-bootclasspath setting.
BootClassPath The JVMs bootclasspath.
CheckJni Performs additional validation on JNI calls if set to true.
ClassPath The application classpath configured for the JVM.
COMExceptionMessages A property governing whether exception type, message, and stack trace are all bundled up in one XML message, that is supplied as the exception's Message property. VB6 clients only have easy access to the message and this would provide all necesssary information if set to true. This property is set to false by default.
DashDOption The property that allows the specification of -D options.
DashXOption The property that allows the specification of -X options.
Debug Starts the embedded JVM in debug mode, allowing an external debugger to attach to it.
DisableClassGC Disables class garbage collection if set to true.
EnableClassGC Enables class garbage collection if set to true.
EnableVerboseGC Enables verbose garbage collection if set to true.
Exit The callback for the JVM exit.
ExtensionDirectories The extensions directory configured for the JVM.
Future Performs strict class-file format checks if set to true.
IgnoreUnrecognized Governs whether an unrecognized configuration option causes a JVM initialization error.
IncrementalGC Incremental GC collects just a portion of the old generation at a time, trying to spread the large pause of a major collection over many minor collections.
InitialHeapSize The initial JVM heap size in MB. This property is synonymous to the InitialHeapSizeInMB property.
InitialHeapSizeInMB The initial JVM heap size in MB. This property is synonymous to the InitialHeapSize property.
InterpretedMode Enables interpreted execution mode if set to true.
JNILevel The JNI Version number to be used for initialization of the JVM. This is synonymous to the JniVersion property.
JniVersion The JNI Version number to be used for initialization of the JVM. This is synonymous to the JNILevel property.
LibraryPath The application librarypath configured for the JVM.
LogGCFile A log file that collects GC log data.
MaximumHeapSize The maximum JVM heap size in MB. This property is synonymous to the MaximumHeapSizeInMB property.
MaximumHeapSizeInMB The maximum JVM heap size in MB. This property is synonymous to the MaximumHeapSize property.
MixedMode Enables mixed execution mode if set to true.
NoAgent The Sun classic VM supports both the old sun.tools.debug interface and JPDA, the option "-Xdebug" enables both, but defaults to running the sun.tools.debug agent. The "-Xnoagent" turns this off so that JPDA will work. The HotSpot VM does not have this option.
PrependBootClassPath The JVMs prepend-to-bootclasspath setting.
Prof Starts the JVM with profiling support enabled if this property is true.
ReduceSignals Reduces usage of operating-system signals by Java Virtual Machine if set to true.
Run Specifies particular runtime settings that are used to configure the debugging or profiling support.
SecurityManager The name of a Java class which acts as the security manager for the session.
SecurityPolicy The name of a file which contains the security policy for the session.
StackSize The stack size in KB is used for the Java stack. This property is synonymous to the StackSizeInKB property.
StackSizeInKB The stack size in KB is used for the Java stack. This property is synonymous to the StackSize property.
UseCodemeshSecurityManager Governs whether a Codemesh SecurityManager is registered instead of the configured one. The Codemesh security manager delegates to the configured one in all but a few cases (the security privileges it needs granted to work).
Verbose The verbosity of the JVM.
Vfprintf The callback for the JVM print statements.
DefaultJvmPath The JVM selected by the runtime library to be used in in-process mode if no JVM path is specified explicitly. This is the full path to a file which is usually called jvm.dll, and resides in a subdirectory of a Java Runtime Environment (JRE). This is a read-only property that allows you to query the choice made by the runtime.
JvmPath The JVM that is used in in-process mode. This is the full path to a file which is usually called jvm.dll and is in a subdirectory of the Java Runtime Environment (JRE).
NoshutdownProcessing Governs whether the application should attempt to perform cleanup in the JVM when shutting down. This defaults to false, but some applications may require setting this property to true if they experience shutdown crashes.
Remote Specifies whether to use in-process or out-of-process runtime mode. If you use a value of true here, you need to configure at least the IRemoteOptions.ConnectionString property.
TraceFile A file into which trace messages are written. If not specified, all tracing output goes to stdout.
TraceMethod Allows you to register a custom tracing method.
ClassesAnalysis A property that can be used to analyze the proxy classes. The returned string contains useful cleartext feedback on the availability of Java types for present proxy types.
ClassPathAnalysis A property that can be used to analyze the classpath. The returned string contains useful cleartext feedback on the correctness of the configured classpath roots.
JvmIfCreated A property giving access to an already created JVM without creating one. This property allows you to query whether a JVM has already been loaded via the JVM Loader API.
MethodsAndFieldsAnalysis A property that can be used to analyze the inner structure of proxy classes. The returned string contains useful cleartext feedback on the availability of Java fields and methods for present proxy type field and method elements.

Public Methods:

Method Description
AppendToBootClassPath Appends a classpath root to the configured bootclasspath. A classpath root is a directory, or a jar file or zip file.
AppendToClassPath Appends a classpath root to the classpath. A classpath root is a directory, or a jar file or zip file.
AppendToExtensionDirectories Appends a directory to the configured extensions directories.
AppendToLibraryPath Appends a directory to the library search path.
PrependToBootClassPath Prepends a classpath root to the configured bootclasspath. A classpath root is a directory, or a jar file or zip file.
PrependToClassPath Prepends a classpath root to the classpath. A classpath root is a directory, or a jar file or zip file.
PrependToLibraryPath Prepends a directory to the librarypath.
GetTraceLevel Queries the trace level for a trace facility.
SetTraceLevel Sets the trace level for a trace facility.
Load Overloaded. Attempts to load a JVM using the configured settings. If the argument is true, an already loaded JVM will be accepted.
Read Overloaded. Explicitly updates the instance with configuration information from the specified source.
UnloadCleanup Performs cleanup behind a recently destroyed JVM.

Converter

The Converter is either implicitly invoked by the API or explicitly invoked by the user to marshall data in and out of the ExternalEntry.

ExternalEntry is a special kind of JavaSpaces Entry that allows users to fill in data using simple methods, and to form standard Jini Entries without implementing the Entry interface or defining public attributes. ExternalEntry objects can be used with all space operations – write, read, take, notify, update, writeMultiple, readMultiple, writeMultiple, updateMultiple and takeMultiple.

The Convertor is an internal facility that converts PONO objects to ExternalEntry and ExternalEntry to PONO.

The Converter allows you to explicitly convert .NET business objects to GigaSpaces Entry representation – the ExternalEntry.  

You can access the Converter from the space proxy using the GigaSpaces.Converter field. 

The Converter includes the following routines:

AddMapping

Allows you to add new mapping types when performing serialization.

  • Creates a new object from type ObjTypeMarshal.
  • Initializes the .NET and Java names.
  • Points the delegated marshal function to the function you implemented.
  • Calls the Converter.AddMapping(ObjTypeMarshal) function, with the new object that was created. 

The Converter adds this to each map in the thread local storage. When serializing, the delegated function is called by the inspector. In order to identify that it's an additional type, the code 777 is used (variable customCode). 

addNewAssembly

Used to analyze and cache the meta data contained in a given assembly for use by the converter.

This method call is only required if the objects you wish to marshall exist outside of the currently executing program. For example, where classes are present inside another .NET assembly such as a class library.

addNewAssembly isn't used in GigaSpaces version 5.2 and onwards. The system automatically determines which assembly is required.

DumpInfo

Prints the Converter information to the trace file. 

Thread ID: 10 23/08/06, 12:52:33: Converter GlobalTypes:
Thread ID: 10 23/08/06, 12:52:33: MyListener
Thread ID: 10 23/08/06, 12:52:33: Person
Thread ID: 10 23/08/06, 12:52:33: Application
Thread ID: 10 23/08/06, 12:52:33: Converter Assemblies:
Thread ID: 10 23/08/06, 12:52:33: MyListener
Thread ID: 10 23/08/06, 12:52:33: Person
Thread ID: 10 23/08/06, 12:52:33: Application

getExternalEntry

Gets an ExternalEntry that represents the user's object.

getNullTemplateEntry

Gets a blank ExternalEntry for the user's object, useful as a wildcard template. The getNullTemplateEntry constructs an instance of the user's object based on the GigaSpaces ExternalEntry.

getTemplateEntry

Gets a template ExternalEntry for the user's object, useful as a wildcard template.

The getTemplateEntryCreates creates an ExternalEntry suitable for use as a search template. Only the field names specified in the args list will be included in the template.

GetTracer

Gets an instance of the Tracer.

indexFields

Add Indexed Fields to the ExternalEntry object

Tracing

Overview

The Tracer is a singleton object used for printing messages to a log file. The Tracer creates a file called gigaspaces.log under the default directory in which the process is running (next to the gs_jini_services_0.log).

To get a handle to the Tracer, use:

GSTracer.Tracer.GetInstacne() 

Tracing Functions

Automatically logs the date, time and thread ID of all messages.

GetInstance

Gets an instance of the Tracer.

SetSevirity

The Tracer can work in 5 different severities: Off, Low, Medium, High, VeryHigh. The SetSevirity method is used to set the severity. The Tracer logs any message with an equal or higher severity. For example, severity = High logs high messages and very high messages. The default value is set to High.

Most trace messages are classified as Low, and high messages are only exceptions and error messages. Therefore, normally no traces should be logged unless there is an exception.

Tracer Method

The SetTraceMethod determines the mode the tracer works in: Buffer or File.

The Tracer stores the messages in memory. The buffer is saved to the log file in two cases:

  1. Calling the function Tracer.flush().
  2. Calling the function TraceNow().

Trace(string)

Used for simply printing a message. Since no severity is defined for the message, it is printed in any case.

Trace(string, Sevirity)

Traces according to the severity. If the severity is lower then the tracer setting, the function doesn't trace anything.

TraceNow(string)

Traces a message and prints it directly (in buffer mode it flushes the buffer). 

Trace(Exception)

Prints the exception and the stack trace.  

Flush

Flushes the tracer data.


Wiki Content Tree


Your Feedback Needed!

We need your help to improve this wiki site. If you have any suggestions or corrections, write to us at techw@gigaspaces.com. Please provide a link to the wiki page you are referring to.

Labels

 
(None)