SpaceProxy Class Reference

List of all members.


Detailed Description

The SpaceProxy is the primary interface that allows you to connect to the space and perform space operations.

The SpaceProxy is used with the different space topologies and runtime modes in a transparent manner. You can use the SpaceProxy object with an embedded, remote, single, or clustered replicated or partitioned space.

The basic space operations include the following:

A space entry is any object that implements the IEntry interface. An IEntry object type is defined in gs.xml file (for more information on gs.xml see http://www.gigaspaces.com/wiki/x/NYHcAQ).
Before performing any space operation using a new IEntry object type, the type must be published to the space by creating a snapshot of this type.

In some operations (for example, read) an entry template should be provided. A template is an IEntry object. Any field in the template that has a specific value is used to match entries with the same value. Any field that is not specified (and therefore has the default 'null' value) is used as a wildcard and will match any value. Note that gs.xml defines for each field its 'null' value.

SqlQuery object is another way to specify a template. SpaceProxy includes appropriate methods that accept SqlQuery argument.

The SpaceProxy supports single and batch space operations. Batch operations are used to optimize space operations with multiple objects and can boost the application performance when interacting with the space.

The SpaceProxy supports Transactions. All relevant space operations accept a Transaction argument.

A SpaceProxy is obtained using the SpaceFinder. Here is an example code:


 SpaceFinder spaceFinder;
 SpaceProxyPtr spaceProxy = spaceFinder.find("jini://lookup-host/container-name/space-name");
 

See also:
SpaceFinder, IEntry, SqlQuery, Transaction, ITransactionManager, DataEventSession, GSIterator

Public Member Functions

void clean ()
void clear (IEntry *pIEntryTemplate, TransactionPtr txn=NULL_TX)
 Removes the entries that match the specified template from this space.
int count (IEntry *pIEntryTemplate, TransactionPtr txn=NULL_TX, ReadModifiers modifiers=REPEATABLE_READ)
 Counts (according to the modifiers) the matching entries from the space, visible under the specified transaction.
void dropClass (std::string className)
SpaceProxyPtr getDirectProxy ()
 Returns a proxy to the local member (partition) in a clustered space.
ITransactionManagerPtr getDistributedTransactionManager (IConfigPtr config)
 Returns a Distributed Transaction Manager through which a distributed Transaction can be obtained.
TransactionPtr getLocalTransaction (long long leaseTime=60000)
 Creates a Local Transaction.
ITransactionManagerPtr getLocalTransactionManager ()
 Returns a Local Transaction Manager through which a Local Transaction can be obtained.
bool isClustered ()
 Returns true if the proxy is connected to a clustered space.
void ping ()
long long proxyId ()
IEntryread (const SqlQuery &sqlQuery, TransactionPtr txn=NULL_TX, long long timeout=0, ReadModifiers modifiers=REPEATABLE_READ)
 Reads any matching entry from the space using SqlQuery template.
template<class T>
T * read (T *pIEntryTemplate, TransactionPtr txn=NULL_TX, long long timeout=0, ReadModifiers modifiers=REPEATABLE_READ)
 Reads (according to the modifiers) any matching entry from the space, blocking until one exists.
template<class T>
T * readIfExists (T *pIEntryTemplate, TransactionPtr txn=NULL_TX, long long timeout=0, ReadModifiers modifiers=REPEATABLE_READ)
 Reads (according to the modifiers) any matching entry from the space, returning NULL if there currently is none.
IEntryVector readMultiple (const SqlQuery &sqlQuery, TransactionPtr txn=NULL_TX, int maxEntries=100000, ReadModifiers modifiers=REPEATABLE_READ)
 Reads any matching entries from the space using SqlQuery template.
IEntryVector readMultiple (IEntry *pIEntryTemplate, TransactionPtr txn=NULL_TX, int maxEntries=100000, ReadModifiers modifiers=REPEATABLE_READ)
 Reads any matching entries from the space.
void restart ()
void setSecurityContext (SecurityContext &context)
 Sets a security context to enable access to a secured space.
void snapshot (IEntry *pIEntryTemplate)
 Enable the space to recognize a given type of Entry object.
void start ()
int state ()
void statistics (std::string className)
void stop ()
IEntrytake (const SqlQuery &sqlQuery, TransactionPtr txn=NULL_TX, long long timeout=0)
 Takes any matching entry from the space using SqlQuery template, blocking until one exists.
template<class T>
T * take (T *pIEntryTemplate, TransactionPtr txn=NULL_TX, long long timeout=0)
 Takes any matching entry from the space, blocking until one exists.
template<class T>
T * takeIfExists (T *pIEntryTemplate, TransactionPtr txn=NULL_TX, long long timeout=0)
 Takes any matching entry from the space, returning NULL if there currently is none.
IEntryVector takeMultiple (const SqlQuery &sqlQuery, TransactionPtr txn=NULL_TX, int maxEntries=100000)
 Takes any matching entries from the space using SqlQuery template.
IEntryVector takeMultiple (IEntry *pIEntryTemplate, TransactionPtr txn=NULL_TX, int maxEntries=100000)
 Takes any matching entries from the space.
void ThreadDetach ()
 Frees the memory allocated in the SpaceProxy for the current thread.
template<class T>
T * update (T *pIEntry, TransactionPtr txn=NULL_TX, long long lease=Lease::FOREVER, long long timeout=0, UpdateModifiers modifiers=UPDATE_ONLY)
 Updates an Entry object in this space.
Lease write (IEntry *pIEntry, TransactionPtr txn, long long lease, UpdateModifiers modifiers)
 Writes an Entry object to this space and returns its Lease.
Lease write (IEntry *pIEntry, TransactionPtr txn=NULL_TX, long long lease=Lease::FOREVER, long long timeout=0, UpdateModifiers modifiers=UPDATE_OR_WRITE)
 Writes an Entry object to this space and returns its Lease.
std::vector< LeasewriteMultiple (const IEntryVector &pIEntryArray, TransactionPtr txn=NULL_TX, long long lease=Lease::FOREVER)
 Writes the specified entries to this space and return their Leases.
virtual ~SpaceProxy ()

Constructor & Destructor Documentation

SpaceProxy::~SpaceProxy (  )  [virtual]

Performs cleanup and releases the proxy.

The Space Proxy Destructor.


Member Function Documentation

void SpaceProxy::clean (  ) 

Cleans the space

void SpaceProxy::clear ( IEntry pIEntryTemplate,
TransactionPtr  txn = NULL_TX 
)

Removes the entries that match the specified template from this space.

If pIEntryTemplate is NULL, all entries are removed.

Sample usage:


 Person personTemplate;	// Empty template to match all Person entries
 // Remove all entries of type Person
 spaceProxy->clear(&personTemplate);
 // Remove all entries of any type
 spaceProxy->clear(NULL);
 

Parameters:
pIEntryTemplate - Pointer to an IEntry template object
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs

int SpaceProxy::count ( IEntry pIEntryTemplate,
TransactionPtr  txn = NULL_TX,
ReadModifiers  modifiers = REPEATABLE_READ 
)

Counts (according to the modifiers) the matching entries from the space, visible under the specified transaction.

Sample usage:


 Person personTemplate;         // Entry template for Person
 personTemplate.name = "Jack";
 // Get total number of Person entries in the space where name equals "Jack"
 int count = spaceProxy->count( &personTemplate);
 

Parameters:
pIEntryTemplate - Pointer to an IEntry template used for matching. Matching is done against template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
modifiers - Operation modifiers that provide the isolation level. Default is REPEATABLE_READ.
Returns:
The number of matching entries
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs

SpaceProxyPtr SpaceProxy::getDirectProxy (  ) 

Returns a proxy to the local member (partition) in a clustered space.

This member is the one that the clustered proxy is directly connected to.
If the original proxy is not part of a cluster, it returns a proxy to the same space as its only member.

Sample usage:


 SpaceFinder spaceFinder;
 SpaceProxyPtr clusterSpaceProxy = spaceFinder.find("jini://lookup-host/container-name/space-name");
 SpaceProxyPtr directProxy = clusterSpaceProxy->getDirectProxy();
 

Returns:
Smart pointer to a new single space proxy that is connected to the local member (partition) in the clustered space.
Exceptions:
RemoteException - if a communication error occurs

ITransactionManagerPtr SpaceProxy::getDistributedTransactionManager ( IConfigPtr  config  ) 

Returns a Distributed Transaction Manager through which a distributed Transaction can be obtained.

Parameters:
config - A Config object that holds the properties relevant for the specific type of the Distributed Transaction Manager.
For a Distributed Transaction Manager based on Jini Mahalo use JiniConfig.
Returns:
Distributed Transaction Manager
Exceptions:
FinderException - if failed to find the Transaction Manager (when using Jini)

TransactionPtr SpaceProxy::getLocalTransaction ( long long  leaseTime = 60000  ) 

Creates a Local Transaction.

Parameters:
leaseTime - The time period in milliseconds until the transaction is discarded.
Default is 60 seconds.
Returns:
New local transaction
Exceptions:
RemoteException - if a communication error occurs
LeaseDeniedException - if the requested leaseTime is denied

ITransactionManagerPtr SpaceProxy::getLocalTransactionManager (  ) 

Returns a Local Transaction Manager through which a Local Transaction can be obtained.

Returns:
Local Transaction Manager

bool SpaceProxy::isClustered (  )  [inline]

Returns true if the proxy is connected to a clustered space.

Returns:
True if the proxy is connected to a clustered space, false if it is connected to a single space.

IEntry * SpaceProxy::read ( const SqlQuery sqlQuery,
TransactionPtr  txn = NULL_TX,
long long  timeout = 0,
ReadModifiers  modifiers = REPEATABLE_READ 
)

Reads any matching entry from the space using SqlQuery template.

Same as read(T pIEntryTemplate, TransactionPtr, long long, ReadModifiers), except that the template is given using SqlQuery.

Sample usage:


 Person personTemplate;
 // Match all Person entries where age is older than 30
 SqlQuery personQuery(&personTemplate, "age > 30");
 PersonPtr personResponse;     // Will hold the entry we read from the space (smart pointer)
 personResponse.reset((Person*)spaceProxy->read( personQuery));
 

Parameters:
sqlQuery - SqlQuery object used for matching.
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
timeout - How much time (in milliseconds) the client is willing to wait for a proper matching entry. Default is 0, meaning waiting no time at all. Use MAX_TIMEOUT to wait indefinitely.
modifiers - Operation modifiers that provide the isolation level. Default is REPEATABLE_READ.
Returns:
A space entry that matches the given SqlQuery object, or NULL if timeout expires and none is found.
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
InterruptedException - if the thread in which the operation occurs is interrupted.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs
See also:
SqlQuery, read()

template<class T>
T* SpaceProxy::read ( T *  pIEntryTemplate,
TransactionPtr  txn = NULL_TX,
long long  timeout = 0,
ReadModifiers  modifiers = REPEATABLE_READ 
) [inline]

Reads (according to the modifiers) any matching entry from the space, blocking until one exists.

Returns NULL if the timeout expires.

To read an entry a template is provided in order to find a matching entry. Any field in the template that has a specific value is used to match entries with the same value. Any field that is not specified (and therefore has the default 'null' value) is used as a wildcard and will match any value.

It is recommended to use a smart pointer to receive the returned entry in order to avoid memory allocation problems.

Sample usage:


 Person personTemplate;             // Entry template for Person
 personTemplate.name = "Jack";
 personTemplate.city = "New York";  // Routing field (must be specified if space is a cluster and timeout > 0)
 PersonPtr personJack;              // Will hold the entry we read from the space (smart pointer)
 // Read a Person entry where 'name' equals "Jack" and 'city' is "New York"
 personJack.reset(spaceProxy->read( &personTemplate, NULL_TX, 10000, DIRTY_READ);
 

Parameters:
pIEntryTemplate - Pointer to an IEntry template used for matching. Matching is done against template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
timeout - How much time (in milliseconds) the client is willing to wait for a proper matching entry. Default is 0, meaning waiting no time at all. Use MAX_TIMEOUT to wait indefinitely.
modifiers - Operation modifiers that provide the isolation level. Default is REPEATABLE_READ.
Returns:
A space entry that matches the given template, or NULL if timeout expires and none is found.
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
InterruptedException - if the thread in which the operation occurs is interrupted.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs

template<class T>
T* SpaceProxy::readIfExists ( T *  pIEntryTemplate,
TransactionPtr  txn = NULL_TX,
long long  timeout = 0,
ReadModifiers  modifiers = REPEATABLE_READ 
) [inline]

Reads (according to the modifiers) any matching entry from the space, returning NULL if there currently is none.

Matching and timeouts are done as in read(), except that blocking in this call is done only if necessary to wait for transactional state to settle.

Parameters:
pIEntryTemplate - Pointer to an IEntry template used for matching. Matching is done against template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
timeout - How much time (in milliseconds) the client is willing to wait for a proper matching entry. Default is 0, meaning waiting no time at all. Use MAX_TIMEOUT to wait indefinitely.
modifiers - Operation modifiers that provide the isolation level. Default is REPEATABLE_READ.
Returns:
A space entry that matches the given template, or NULL if no such entry exists.
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
InterruptedException - if the thread in which the operation occurs is interrupted.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs
See also:
read()

IEntryVector SpaceProxy::readMultiple ( const SqlQuery sqlQuery,
TransactionPtr  txn = NULL_TX,
int  maxEntries = 100000,
ReadModifiers  modifiers = REPEATABLE_READ 
)

Reads any matching entries from the space using SqlQuery template.

Same as readMultiple(IEntry* pIEntryTemplate, TransactionPtr, int, ReadModifiers) except that the template is given using SqlQuery

Parameters:
sqlQuery - SqlQuery object used for matching.
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
maxEntries - Maximum number of entries to be returned. Default is 100000.
modifiers - Operation modifiers that provide the isolation level. Default is REPEATABLE_READ.
Returns:
A vector of all space entries that match the given SqlQuery, limited by maxEntries. The vector is empty if no matching entry is found.
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs
See also:
SqlQuery, read(), readMultiple()

IEntryVector SpaceProxy::readMultiple ( IEntry pIEntryTemplate,
TransactionPtr  txn = NULL_TX,
int  maxEntries = 100000,
ReadModifiers  modifiers = REPEATABLE_READ 
)

Reads any matching entries from the space.

Matching is done as in read() without timeout (timeout = 0). Returns a vector of matched entries. The amount of entries returned is limited by maxEntries. Returns an empty vector if no match was found.

Sample usage:


 Person personTemplate;               // Entry template for Person
 personTemplate.city = "New York";    // Match all person entries that live in 'New York'.
 IEntryVector responseBatch;
 // Read all Person entries that live in New York (at most 1000 entries)
 responseBatch = spaceProxy->readMultiple(&personTemplate, NULL_TX, 1000, DIRTY_READ);
 // Memory cleanup
 for (int i = 0; i < responseBatch.size(); i++) {
	delete responseBatch[i];
 }
 

Parameters:
pIEntryTemplate - Pointer to an IEntry template used for matching. Matching is done against template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
maxEntries - Maximum number of entries to be returned. Default is 100000.
modifiers - Operation modifiers that provide the isolation level. Default is REPEATABLE_READ.
Returns:
A vector of all space entries that match the given template, limited by maxEntries. The vector is empty if no matching entry is found.
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs

void SpaceProxy::setSecurityContext ( SecurityContext context  ) 

Sets a security context to enable access to a secured space.

When a space is secured, operations (like read/write) are not enabled and will throw SpaceSecurityException, unless you specify the security context (username and password). It is therefore recommended to set the security context immediately after obtaining a proxy to a secured space.

Sample usage:


 SecurityContext sc("user1", "1234");
 spaceProxy->setSecurityContext(sc);
 

Parameters:
context - The SecurityContext (username and password) that grants access to the secured space.
Exceptions:
SpaceSecurityException - indicates a security violation.
RemoteException - if a communication error occurs

void SpaceProxy::snapshot ( IEntry pIEntryTemplate  ) 

Enable the space to recognize a given type of Entry object.

Before performing any space operation using a new IEntry type (IEntry derived-class), the type must be published to the space by creating a snapshot of a template of this type.

Sample usage:


 Person personTemplate;
 spaceProxy->snapshot(&personTemplate);
 

Parameters:
pIEntryTemplate - Pointer to an IEntry template object
Exceptions:
RemoteException - if a communication error occurs

IEntry * SpaceProxy::take ( const SqlQuery sqlQuery,
TransactionPtr  txn = NULL_TX,
long long  timeout = 0 
)

Takes any matching entry from the space using SqlQuery template, blocking until one exists.

Return NULL if the timeout expires.

Same as take(T pIEntryTemplate, TransactionPtr, long long), except that the template is given using SqlQuery.

Sample usage:


 Person personTemplate;
 // Match all Person entries where age is older than 30
 SqlQuery personQuery(&personTemplate, "age > 30");
 PersonPtr personResponse;     // Will hold the entry we take from the space (smart pointer)
 personResponse.reset((Person*)spaceProxy->take( personQuery);
 

Parameters:
sqlQuery - SqlQuery object used for matching.
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
timeout - How much time (in milliseconds) the client is willing to wait for a proper matching entry. Default is 0, meaning waiting no time at all. Use MAX_TIMEOUT to wait indefinitely.
Returns:
A space entry that matches the given SqlQuery object, or NULL if timeout expires and none is found.
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
InterruptedException - if the thread in which the operation occurs is interrupted.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs
See also:
SqlQuery, take()

template<class T>
T* SpaceProxy::take ( T *  pIEntryTemplate,
TransactionPtr  txn = NULL_TX,
long long  timeout = 0 
) [inline]

Takes any matching entry from the space, blocking until one exists.

Returns NULL if the timeout expires.

Sample usage:


 Person personTemplate;             // Entry template for Person
 personTemplate.name = "Jack";
 personTemplate.city = "New York";  // Routing field (must be specified if space is a cluster and timeout > 0)
 PersonPtr personJack;              // Will hold the entry we take from the space (smart pointer)
 // Take a Person entry with name "Jack" and city equals "New York" from the space. Wait 10 seconds at most.
 personJack.reset(spaceProxy->take( &personTemplate, NULL_TX, 10000);
 

Parameters:
pIEntryTemplate - Pointer to an IEntry template used for matching. See read() for more information on using templates.
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
timeout - How much time (in milliseconds) the client is willing to wait for a proper matching entry. Default is 0, meaning waiting no time at all. Use MAX_TIMEOUT to wait indefinitely.
Returns:
A space entry that matches the given template, or NULL if timeout expires and none is found.
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
InterruptedException - if the thread in which the operation occurs is interrupted.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs
See also:
read()

template<class T>
T* SpaceProxy::takeIfExists ( T *  pIEntryTemplate,
TransactionPtr  txn = NULL_TX,
long long  timeout = 0 
) [inline]

Takes any matching entry from the space, returning NULL if there currently is none.

Matching and timeouts are done as in take(), except that blocking in this call is done only if necessary to wait for transactional state to settle.

Parameters:
pIEntryTemplate - Pointer to an IEntry template used for matching. See read() for more information on using templates.
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
timeout - How much time (in milliseconds) the client is willing to wait for a transactionally proper matching entry. Default is 0, meaning waiting no time at all. Use MAX_TIMEOUT to wait indefinitely.
Returns:
A space entry that matches the given template, or NULL if no such entry exists.
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
InterruptedException - if the thread in which the operation occurs is interrupted.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs
See also:
take()

IEntryVector SpaceProxy::takeMultiple ( const SqlQuery sqlQuery,
TransactionPtr  txn = NULL_TX,
int  maxEntries = 100000 
)

Takes any matching entries from the space using SqlQuery template.

Same as takeMultiple(IEntry* pIEntryTemplate, TransactionPtr, int) except that the template is given using SqlQuery.

Parameters:
sqlQuery - SqlQuery object used for matching.
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
maxEntries - Maximum number of entries to be returned. Default is 100000.
Returns:
A vector of all space entries that match the given SqlQuery, limited by maxEntries. The vector is empty if no matching entry is found.
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs
See also:
SqlQuery, take(), takeMultiple()

IEntryVector SpaceProxy::takeMultiple ( IEntry pIEntryTemplate,
TransactionPtr  txn = NULL_TX,
int  maxEntries = 100000 
)

Takes any matching entries from the space.

Matching is done as in take() without timeout (timeout = 0). Returns a vector of matched entries. The amount of entries returned is limited by maxEntries. Returns an empty vector if no match was found.

Sample usage:


 Person personTemplate;               // Entry template for Person
 personTemplate.age = 30;
 IEntryVector responseBatch;
 // Take all Person entries with age 30 (at most 1000 entries)
 responseBatch = spaceProxy->takeMultiple(&personTemplate, NULL_TX, 1000);
 // Memory cleanup
 for (int i = 0; i < responseBatch.size(); i++) {
	delete responseBatch[i];
 }
 

Parameters:
pIEntryTemplate - Pointer to an IEntry template used for matching. Matching is done against template with null fields being wildcards ("match anything") other fields being values ("match exactly on the serialized form").
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
maxEntries - Maximum number of entries to be returned. Default is 100000.
Returns:
A vector of all space entries that match the given template, limited by maxEntries. The vector is empty if no matching entry is found.
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs

void SpaceProxy::ThreadDetach (  ) 

Frees the memory allocated in the SpaceProxy for the current thread.

Call this before the thread exits.

template<class T>
T* SpaceProxy::update ( T *  pIEntry,
TransactionPtr  txn = NULL_TX,
long long  lease = Lease::FOREVER,
long long  timeout = 0,
UpdateModifiers  modifiers = UPDATE_ONLY 
) [inline]

Updates an Entry object in this space.

An update can be performed, with these modifiers listed in UpdateModifiers:

Sample usage:


 // Write a Person object in space
 Person person;
 person.name = "Jack";
 person.age = 30;
 person.city = "New York";	// Routing field (must be specified if space is a cluster)
 spaceProxy->write(&person);
 // Update age
 person.age = 35;
 PersonPtr oldPerson;		// Use smart pointer to hold the old value
 oldPerson.reset(spaceProxy->update(&person);
 

Parameters:
pIEntry - Pointer to IEntry object to be updated.
txn - Transaction object, if any, under which to perform the operation. Default is NULL_TX.
lease - Requested lease time, in milliseconds. Default is Lease::FOREVER.
timeout - How much time (in milliseconds) the client is willing to wait for a proper matching entry. Default is 0, meaning waiting no time at all. Use MAX_TIMEOUT to wait indefinitely.
modifiers - Operation modifiers. Default is UPDATE_ONLY.
Returns:
The previous value on success, otherwise NULL.
For write operation (using UPDATE_OR_WRITE and entry is new) return NULL on success.
Exceptions:
UnusableEntryException - if any serialized field of the object being read cannot be deserialized for any reason.
InterruptedException - if the thread in which the operation occurs is interrupted.
IllegalArgumentException - if the lease time requested is not Lease::ANY and is negative.
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs

Lease SpaceProxy::write ( IEntry pIEntry,
TransactionPtr  txn,
long long  lease,
UpdateModifiers  modifiers 
) [inline]

Writes an Entry object to this space and returns its Lease.

Overloaded function for backward compatibility. Use write(IEntry* pIEntry, TransactionPtr txn, long long lease, long long timeout, UpdateModifiers modifiers) instead.

Lease SpaceProxy::write ( IEntry pIEntry,
TransactionPtr  txn = NULL_TX,
long long  lease = Lease::FOREVER,
long long  timeout = 0,
UpdateModifiers  modifiers = UPDATE_OR_WRITE 
)

Writes an Entry object to this space and returns its Lease.

Applying the UPDATE_OR_WRITE modifier, is equivalent to calling update(), but otherwise returning a Lease on a successful write.

The operation can also be forced to perform write operation using the WRITE_ONLY modifier, resulting in an EntryAlreadyInSpaceException if the object already exists in the space.

Sample usage:


 Person person;
 person.name = "Jack";
 person.city = "New York";	// Routing field (must be specified if space is a cluster)
 person.age = 40;
 Lease lease = spaceProxy->write( &person, NULL_TX, Lease::FOREVER, 1000, WRITE_ONLY);
 

Parameters:
pIEntry - Pointer to IEntry object to be written.
txn - Transaction object, if any, under which to perform the operation. Default is NULL_TX.
lease - Requested lease time, in milliseconds. Default is Lease::FOREVER.
timeout - Requested timeout waiting duration, in milliseconds. Default is 0.
modifiers - Operation modifiers. Default is UPDATE_OR_WRITE.
Returns:
The Lease for the written entry
Exceptions:
EntryAlreadyInSpaceException - if an entry with the same UID already exists in space (Modifiers::WRITE)
EntryNotInSpaceException - if an entry with such a UID doesn't exits in the space (Modifiers::UPDATE)
OperationTimeoutException - if timeout expires (when used with UPDATE_OR_WRITE modifier)
TransactionException - if a Transaction error occurs
RemoteException - if a communication error occurs

std::vector< Lease > SpaceProxy::writeMultiple ( const IEntryVector pIEntryArray,
TransactionPtr  txn = NULL_TX,
long long  lease = Lease::FOREVER 
)

Writes the specified entries to this space and return their Leases.

Sample usage:


 // Prepare a vector (batch) of Person objects
 IEntryVector myBatch(100);
 for (int i = 0; i < 100; i++) {
	Person* pPerson = new Person;
	pPerson->name = "Jack";
	pPerson->city = i % 2 ? "New York" : "London";	// Routing field (must be specified if space is a cluster)
	pPerson->age = i;
	myBatch[i] = pPerson;
 }

 // Write the batch
 std::vector<Lease> results = spaceProxy->writeMultiple(myBatch,NULL_TX,Lease::FOREVER);

 // Memory cleanup
 for (int i = 0; i < 100; i++) {
	delete myBatch[i];
 }
 

Parameters:
pIEntryArray - Vector of IEntry objects to write.
txn - The Transaction object, if any, under which to perform the operation. Default is NULL_TX.
lease - Requested lease time, in milliseconds. Default is Lease::FOREVER.
Returns:
Vector of Leases for the written entries.
Exceptions:
TransactionException - if a transaction error occurs
RemoteException - if a communication error occurs
IllegalArgumentException - if the lease time requested is not Lease::ANY and is negative


Generated on Wed Sep 16 16:59:14 2009 for GigaSpaces XAP 7.0.1 C++ by  doxygen 1.5.3