APL - PCC BucketData Support - Buckets(3.0)

Owned by Former user (Deleted)
Last updated: Apr 20, 2023 by Jenni Wallin
4 min read

The BucketData APL functions are used for managing the storage of bucket data objects.

The BucketData Support functions include:

  • pccBeginBucketDataTransaction

  • pccBucketDataLookup

  • pccBucketDataLookupMany

  • pccBucketDataStore

  • pccCommitBucketDataTransaction

  • pccRollbackBucketDataTransaction

  • pccBucketDataRemove

  • pccCreateBucketDataKeyIterator

  • pccDestroyBucketDataKeyIterator

  • pccHasNextBucketDataKey

  • pccGetNextBucketDataKey

  • pccGetNextBucketDataKeys

pccBeginBucketDataTransaction

Creates a transaction object that can be called when using transaction lock.

any pccBeginBucketDataTransaction()

Parameters

ParameterDescription

Returns:

A transaction object.

Example

any myTransaction = pccBeginBucketDataTransaction ();

will create a transaction object named myTransaction .

pccBucketDataLookup

Retrieves the BucketDataHolder object with the stated key from storage.

BucketDataHolder pccBucketDataLookup( string key, any txn )

Parameters

ParameterDescription

key

The key that uniquely identifies the BucketDataHolder object.

txn

States the transaction object to be used when using transaction lock. If transaction lock is not used, this parameter should be set to null .

Returns:

The BucketDataHolder object, if it was found in the storage, otherwise null.

Example

pccBucketDataLookup ("555", myTransaction);

will retrieve a BucketDataHolder object with key 555 from storage and apply transaction lock with the transaction object myTransaction .

pccBucketDataLookupMany

Retrieves a number of BucketDataHolder objects included in the stated list from storage.

map<string, BucketDataHolder> pccBucketDataLookupMany
( list<string> keys, any txn )

Parameters

ParameterDescription

keys

The list of keys that uniquely identify the BucketDataHolder objects.

txn

States the transaction object to be used when using transaction lock. If transaction lock is not used, this parameter should be set to null .

Returns:

The BucketDataHolder objects, if they were found in the storage, otherwise an empty map.

Example

pccBucketDataLookupMany(myList, myTransaction);

will retrieve the BucketDataHolder objects stated in the myList list from storage and apply transaction lock with the transaction object myTransaction .

pccBucketDataStore

Stores the BucketDataHolder object to storage.

boolean pccBucketDataStore
( string key, BucketDataHolder bdh, any txn [, boolean throwException] )

Parameters

ParameterDescription

key

The key that uniquely identifies the BucketDataHolder object.

bdh

The BucketDataHolder object to store.

txn

States the transaction object to be used when using transaction lock. If transaction lock is not used, this parameter should be set to null .

throwException

An optional parameter that can be set to false to be able to handle any storage errors. In this case the return value has to be checked and the pccLastError* functions to get the actual error (see APL - PCC Provisioning Plugins - Buckets(3.0)).

expiration

An optional parameter that can be set to an integer value in seconds. This value is the TTL (Time-To-Live) for the BucketDataHolder object passed along with it. This parameter is only supported for Couchbase data store, versions 5.5 and above.

Note!

If you use the expiration parameter, it is mandatory to set five (5) parameters for the pccBucketDataStore function.

If the expiration parameter is not set, TTL will be zero (0) per default / bucket default. Zero is interpreted as infinity. If only three or four parameters are supplied to the pccBucketDataStore function, TTL will be 0.

If transaction (txn) is used, TTL start time will be from the time of transaction commit (pccCommitBucketDataTransaction).

Returns:

True if the operation succeeded. This will always be the case unless throwException is set to false.

Example

pccBucketDataStore("777", myBucket, myTransaction, true, 60);

In the case of using a Couchbase data store, the above function stores the myBucket BucketDataHolder object with 60 seconds TTL and key 777, while adding the BucketDataHolder object into the transaction object myTransaction.

In the case of any other data store, the above function stores the myBucket BucketDataHolder object with key 777, while adding the BucketDataHolder object into the transaction object myTransaction.

pccCommitBucketDataTransaction

Commits the changes that have been made to the BucketDataHolder objects that are using the stated transaction object.

void pccCommitBucketDataTransaction( any  txn  )

Parameters

ParameterDescription

txn

The transaction object for which changes should be committed.

Example

pccCommitBucketDataTransaction (myTransaction);

will commit the changes made to the BucketDataHolder objects using the myTransaction transaction object.

pccRollbackBucketDataTransaction

Removes any changes that have been made to the BucketDataHolder objects that are using the stated transaction object.

void pccRollbackBucketDataTransaction( any txn )

Parameters

ParameterDescription

txn

The transaction object for which changes should be rolled back.

Example

pccRollbackBucketDataTransaction (myTransaction);

will rollback the changes made to the BucketDataHolder objects using the myTransaction transaction object.

pccBucketDataRemove

Removes a BucketDataHolder object from storage.

void pccBucketDataRemove( string key, any txn )

Parameters

ParameterDescription

key

The key that uniquely identifies the BucketDataHolder object.

txn

The transaction when transaction lock is used.

Example

pccBucketDataRemove ("754", myTransaction);

will remove the BucketDataHolder object with key 754> from storage and apply transaction lock with the transaction object >myTransaction .

pccCreateBucketDataKeyIterator

Creates an iterator which is used for moving from key to key in the database.

any pccCreateBucketDataKeyIterator( [string startKey [, string stopKey]] )

Parameters

ParameterDescription

startKey

Optional parameter for stating which key to start with. This key will also be included.

stopKey

Optional parameter for stating which key to end with. This key will also be included.

Returns:

The iterator that has been created.

Example

any myIterator = pccCreateBucketDataKeyIterator( );

will create an iterator named myIterator .

pccDestroyBucketDataKeyIterator

Removes the stated iterator and returns all the resources that are being used.

void pccDestroyBucketDataKeyIterator( any iterator )

Parameters

ParameterDescription

iterator

The iterator you want to remove.

Example

pccDestroyBucketDataKeyIterator(myIterator);

will remove the iterator named myIterator .

pccHasNextBucketDataKey

Asks the iterator if there are more keys to retrieve.

boolean pccHasNextBucketDataKey( any iterator

Parameters

ParameterDescription

iterator

The iterator you want to ask.

Returns:

Information whether there is more data to retrieve or not. If true is returned, there is more data to be retrieved with the pccGetNextBucketDataKey function. If false is returned, there is no more data and the function pccGetNextBucketDataKey should not be called again.

Example

pccDestroyBucketDataKeyIterator(myIterator);

will return the next key from the iterator named myIterator if the iterator has next key.

pccGetNextBucketDataKey

Retrieves the next key from the iterator.

string pccGetNextBucketDataKey( any iterator )

Parameters

ParameterDescription

iterator

The iterator you want to retrieve the key from.

Returns:

The next key, or null if no more keys are available.

Example

string key = pccGetNextBucketDataKey(myIterator);

will return the next key from the iterator named myIterator .

pccGetNextBucketDataKeys

Retrieves several keys from the iterator.

list<string> pccGetNextBucketDataKeys( any iterator [, int count] )

Parameters

ParameterDescription

iterator

The iterator you want to retrieve the keys from.

count

Optional parameter for controlling the maximum number of keys to retrieve.

Returns:

A list containing the retrieved keys.

Example

list<string> keys = pccGetNextBucketDataKeys(myIterator, 5);

will return a list of maximum 5 keys with the name keys from the iterator named myIterator .