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:
write
- Writes an entry into the space. read
- Reads an entry from the space that matches a given template. take
- Removes an entry from the space that matches the given template. update
- Updates an entry in the space. notify
- Notifies a specified listener object, when an entry that matches a given template is written/taken/updated/expires in the space. For more information see DataEventSession.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");
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 () |
IEntry * | 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. | |
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 () |
IEntry * | 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. | |
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< Lease > | writeMultiple (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 () |
SpaceProxy::~SpaceProxy | ( | ) | [virtual] |
Performs cleanup and releases the proxy.
The Space Proxy Destructor.
void SpaceProxy::clean | ( | ) |
Cleans the space
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);
pIEntryTemplate | - Pointer to an IEntry template object | |
txn | - The Transaction object, if any, under which to perform the operation. Default is NULL_TX . |
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);
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 . |
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();
RemoteException | - if a communication error occurs |
ITransactionManagerPtr SpaceProxy::getDistributedTransactionManager | ( | IConfigPtr | config | ) |
Returns a Distributed Transaction Manager through which a distributed Transaction can be obtained.
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. |
FinderException | - if failed to find the Transaction Manager (when using Jini) |
TransactionPtr SpaceProxy::getLocalTransaction | ( | long long | leaseTime = 60000 |
) |
Creates a Local Transaction.
leaseTime | - The time period in milliseconds until the transaction is discarded. Default is 60 seconds. |
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.
bool SpaceProxy::isClustered | ( | ) | [inline] |
Returns true if the proxy is connected to a clustered 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));
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 . |
NULL
if timeout
expires and none is found.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 |
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);
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 . |
NULL
if timeout
expires and none is found.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 |
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.
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 . |
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 |
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
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 . |
maxEntries
. The vector is empty if no matching entry is found.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 |
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];
}
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 . |
maxEntries
. The vector is empty if no matching entry is found.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);
context | - The SecurityContext (username and password) that grants access to the secured space. |
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);
pIEntryTemplate | - Pointer to an IEntry template object |
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);
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. |
NULL
if timeout
expires and none is found.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 |
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);
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. |
NULL
if timeout
expires and none is found.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 |
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.
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. |
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 |
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.
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 . |
maxEntries
. The vector is empty if no matching entry is found.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 |
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];
}
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 . |
maxEntries
. The vector is empty if no matching entry is found.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.
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:
UPDATE_ONLY
- pure update operation, UPDATE_OR_WRITE
- writes if absent or updates existing, PARTIAL_UPDATE
- updates only non-null fields.
// 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);
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 . |
NULL
.UPDATE_OR_WRITE
and entry is new) return NULL
on success.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);
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 . |
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];
}
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 . |
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 |