Blob Class Reference

List of all members.


Detailed Description

A special type of field in an IEntry derived class that encapsulates any binary data.

The Blob serializes binary data more efficiently than using types like byte[] or char[].

A field of type Blob is initialized by providing a void pointer to a binary data buffer and the length of the buffer.
The Blob supports two modes:

In order to define a field of type Blob in your IEntry derived class, you specify in the class definition in gs.xml that the field is of type blob.
For example, the following is a definition of an object that has two Blob fields, blobBuffer and blobBufferBinary (the latter is using binary storage type):

 <class name="com.gigaspaces.tests.test_blob" cpp-name="EntryWithBlob" dotnet-name="GigaSpaces.Tests.Interop.test_blob" persist="true" replicate="true" fifo="false" >
	<property name="idField" type="string" null-value="" />
	<id name="idField" auto-generate="true" />
	<property name="intIndex" type="int" null-value="0" index="true"/>
	<routing name="intIndex">
	<property name="blobBuffer" type="blob">
	<property name="blobBufferBinary" type="blob" storage-type="binary" />
 </class>
 

Here is an example for using the Blob:


 void writeData(void* buffer, int length)
 {
	// Writing the entry to the space
	EntryWithBlob entry;
	entry.intIndex = 1;
	entry.blobBuffer.reset(buffer, length, Blob::Unmanaged);
	globalProxy->write(&entry);
 }

 void readData()
 {
	// Reading the entry from the space
	EntryWithBlobPtr spaceEntry;
	EntryWithBlob entryWithBlobTemplate;
	entryWithBlobTemplate.intIndex = 1;
	spaceEntry.reset(globalProxy->read(&entryWithBlobTemplate));

	// Accessing the data
	void* buffer = spaceEntry->blobBuffer.getBuffer();
	// ...
	// Performing operations using buffer provided that spaceEntry is not destroyed
	// ...

	// Getting ownership of the data.
	buffer = spaceEntry->blobBuffer.detachBuffer();
	// The variable 'buffer' now points to the data memory while the 'blobBuffer' field
	// is empty.
	spaceEntry.reset();	// Destroying the content of spaceEntry. We can continue using 'buffer'.
	// ...
	// Performing operations using buffer
	// ...
	// Memory cleanup (since we got ownership of the data it's our responsibility to release it)
	delete buffer;
 }
 

Note:
A Blob is simply an easier and more efficient way to serialize a user's buffer of data. The data is kept in the space as is, so its size is bound by the space memory limitations. If the data exceedes the space memory capacity then any attempt to write it to the space may trigger an exception.
Author:
Irit Rosdeutscher

Public Types

enum  Mode { Unmanaged, Managed }
 Mode of memory management in the Blob. More...

Public Member Functions

 Blob (const Blob &blob)
 Copy constructor.
 Blob (void *p, int length, Mode mode)
 Constructs a Blob that encapsulates a given binary data.
 Blob ()
 Default constructor - constructs an empty Blob.
void * detachBuffer ()
 Enables the user to get ownership of the data.
void * getBuffer ()
 Returns a pointer to the data.
int getLength ()
 Returns the length of the data.
Mode getMode ()
 Returns the mode that specifies how the data is kept (either Unmanaged or Managed).
bool isEmpty ()
 Returns whether the Blob holds any data.
Bloboperator= (const Blob &blob)
 Assigns new content to the Blob based on another blob.
void reset (void *p, int length, Mode mode)
 Initializes the Blob with new content.
void reset ()
 Releases the Blob's content and leaves it empty.
virtual ~Blob (void)
 Performs any required memory cleanup.

Member Enumeration Documentation

enum Blob::Mode

Mode of memory management in the Blob.

Enumerator:
Unmanaged  The Blob points to the user's data and it is the user's responsibiliby to release the memory.
Managed  The Blob holds a copy of the user's data and is responsible for allocating and releasing its own memory.


Constructor & Destructor Documentation

Blob::Blob (  ) 

Default constructor - constructs an empty Blob.

Blob::Blob ( void *  p,
int  length,
Mode  mode 
)

Constructs a Blob that encapsulates a given binary data.

Parameters:
p - Pointer to the binary data
length - The length in bytes of the binary data
mode - Either Unmanaged or Managed (see Mode)

Blob::Blob ( const Blob blob  ) 

Copy constructor.

Parameters:
blob - Other blob to copy from
Note:
If the mode is Managed then the data is not copied only a reference is added to it.

Blob::~Blob ( void   )  [virtual]

Performs any required memory cleanup.


Member Function Documentation

void * Blob::detachBuffer (  ) 

Enables the user to get ownership of the data.

A pointer to the data is returned and the content of the Blob is released so it becomes empty.

Returns:
A void pointer to the data
Note:
If the mode is Managed then it is now the responsibility of the user to release the memory of the data.

void * Blob::getBuffer (  ) 

Returns a pointer to the data.

Returns:
A void pointer to the data
Note:
Any change done to the data via the returned pointer will affect the content of the Blob and may cause errors.

int Blob::getLength (  )  [inline]

Returns the length of the data.

Returns:
The length of the data

Mode Blob::getMode (  )  [inline]

Returns the mode that specifies how the data is kept (either Unmanaged or Managed).

Returns:
The mode of the Blob

bool Blob::isEmpty (  )  [inline]

Returns whether the Blob holds any data.

Returns:
true if the Blob is empty and holds no data

Blob & Blob::operator= ( const Blob blob  ) 

Assigns new content to the Blob based on another blob.

All previous content of this Blob is released.

Parameters:
blob - Other blob

void Blob::reset ( void *  p,
int  length,
Mode  mode 
)

Initializes the Blob with new content.

All previous content is released.

Parameters:
p - Pointer to the binary data
length - The length in bytes of the binary data
mode - Either Unmanaged or Managed (see Mode)

void Blob::reset (  ) 

Releases the Blob's content and leaves it empty.


Generated on Thu Jul 22 08:11:54 2010 for GigaSpaces XAP 11.0 C++ by  doxygen 1.5.3