public interface MCvalueStorage
By default the toolkit stores large attribute values in memory or temporary files, depending on configuration and value size. This interface can be used for application defined value storage locations and strategies.
Value storage instances are obtained by the toolkit from registered value storage providers. A separate
instance is used for each attribute. See MCvalueStorageProvider
and
MCapplication.registerValueStorageProvider(MCvalueStorageProvider, int)
for more details.
The methods of this interface may be called in arbitrary threads but the toolkit ensures that calls are synchronized and no two calls will occur simultaneously.
If a method throws an exception the toolkit will report the exception to the operation that triggered the call (e.g. message read/write) and the operation will be aborted.
Modifier and Type | Method and Description |
---|---|
java.nio.ByteBuffer |
provideData(boolean first)
This method is called by the toolkit to obtain data for the attribute's value.
|
long |
provideDataLength()
This method is called by the toolkit to obtain the length of the attribute's value.
|
void |
receiveData(java.nio.ByteBuffer data,
boolean first,
boolean last)
The toolkit calls this method to store data for the attribute's value.
|
void |
receiveDataLength(long dataLen)
The toolkit calls this method to tell the storage how large the value is.
|
void |
receiveMediaDataLength(long dataLen,
long dataOffset)
This method is called by the toolkit to provide the attribute's value length and the byte offset
in the source stream where the value begins.
|
void |
receiveOffsetTable(java.nio.ByteBuffer data,
boolean first,
boolean last)
The toolkit calls this method to store the offset table of an encapsulated value.
|
void |
reset()
This method is called by the toolkit to notify the storage when it no longer needs the value
stored by this instance.
|
java.nio.ByteBuffer provideData(boolean first)
The toolkit calls this method when it needs the attribute's value for encoding. If the first call
does not return the whole value, the toolkit will make subsequent calls until the return value is
null
.
An implementation is expected to set the position and limit on the returned byte buffer so that its
remaining()
method returns the number of bytes provided by the current call.
If the returned buffer is a direct buffer (backed by native memory) the toolkit will try to avoid marshaling the data into the managed memory passing the native buffer directly to the native code.
first
- true
if the toolkit is requesting data from the beginning of the value,
false
if the toolkit is requesting data that follows the data returned by a previous
call.null
.long provideDataLength()
The toolkit usually calls this method before calling provideData(boolean)
for the first time.
The value 0xFFFFFFFF (UNDEFINED_LENGTH) may be returned if the attribute contains encapsulated data.
void receiveData(java.nio.ByteBuffer data, boolean first, boolean last)
The toolkit uses this method to pass the attribute's value to the custom storage implementation. The method is expected to store the data available in the provided byte buffer between its current position and its limit.
The byte buffer is normally a direct byte buffer, backed by a native memory buffer that is valid for the duration of the call only.
data
- The byte buffer containing part of the value. The buffer's content is valid only for the
duration of the call and it should be processed before the method returns.first
- true
if this is the first piece of data provided by the toolkit.last
- true
if this is the last piece of data provided by the toolkit.void receiveDataLength(long dataLen)
This method is called before any receive data call.
dataLen
- The number of bytes of the attribute's value or 0xFFFFFFFF if the value is
encapsulated and has undefined length.void receiveOffsetTable(java.nio.ByteBuffer data, boolean first, boolean last)
The toolkit uses this method to pass the offset table part of an encapsulated value to the custom storage implementation. The offset table data is available in the provided byte buffer between its current position and its limit.
The byte buffer is normally a direct byte buffer, backed by a native memory buffer that is valid for the duration of the call only.
data
- The byte buffer containing part of the value. The buffer's content is valid only for the
duration of the call and it should be processed before the method returns.first
- true
if this is the first piece of data provided by the toolkit.last
- true
if this is the last piece of data provided by the toolkit.void receiveMediaDataLength(long dataLen, long dataOffset)
See the description of the MCfile.readP10FileBypassBulk(String)
method description for
details on when this method is called by the toolkit.
dataLen
- The length in bytes of the attribute's value.dataOffset
- The byte offset where the value begins in the source stream.void reset()