org.lmdbjava.BufferProxy Maven / Gradle / Ivy
/*-
* #%L
* LmdbJava
* %%
* Copyright (C) 2016 - 2020 The LmdbJava Open Source Project
* %%
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
* #L%
*/
package org.lmdbjava;
import static java.lang.Long.BYTES;
import jnr.ffi.Pointer;
/**
* The strategy for mapping memory address to a given buffer type.
*
*
* The proxy is passed to the {@link Env#create(org.lmdbjava.BufferProxy)}
* method and is subsequently used by every {@link Txn}, {@link Dbi} and
* {@link Cursor} associated with the {@link Env}.
*
* @param buffer type
*/
@SuppressWarnings("checkstyle:AbstractClassName")
public abstract class BufferProxy {
/**
* Size of a MDB_val pointer in bytes.
*/
protected static final int MDB_VAL_STRUCT_SIZE = BYTES * 2;
/**
* Offset from a pointer of the MDB_val.mv_data field.
*/
protected static final int STRUCT_FIELD_OFFSET_DATA = BYTES;
/**
* Offset from a pointer of the MDB_val.mv_size field.
*/
protected static final int STRUCT_FIELD_OFFSET_SIZE = 0;
/**
* Allocate a new buffer suitable for passing to
* {@link #out(java.lang.Object, jnr.ffi.Pointer, long)}.
*
* @return a buffer for passing to the out method
*/
protected abstract T allocate();
/**
* Compare the two buffers.
*
*
* Implemented as a protected method to discourage use of the buffer proxy
* in collections etc (given by design it wraps a temporary value only).
*
* @param o1 left operand
* @param o2 right operand
* @return as per {@link Comparable}
*/
protected abstract int compare(T o1, T o2);
/**
* Deallocate a buffer that was previously provided by {@link #allocate()}.
*
* @param buff the buffer to deallocate (required)
*/
protected abstract void deallocate(T buff);
/**
* Obtain a copy of the bytes contained within the passed buffer.
*
* @param buffer a non-null buffer created by this proxy instance
* @return a copy of the bytes this buffer is currently representing
*/
protected abstract byte[] getBytes(T buffer);
/**
* Called when the MDB_val should be set to reflect the passed
* buffer. This buffer will have been created by end users, not
* {@link #allocate()}.
*
* @param buffer the buffer to write to MDB_val
* @param ptr the pointer to the MDB_val
* @param ptrAddr the address of the MDB_val pointer
*/
protected abstract void in(T buffer, Pointer ptr, long ptrAddr);
/**
* Called when the MDB_val should be set to reflect the passed
* buffer.
*
* @param buffer the buffer to write to MDB_val
* @param size the buffer size to write to MDB_val
* @param ptr the pointer to the MDB_val
* @param ptrAddr the address of the MDB_val pointer
*/
protected abstract void in(T buffer, int size, Pointer ptr, long ptrAddr);
/**
* Called when the MDB_val may have changed and the passed buffer
* should be modified to reflect the new MDB_val.
*
* @param buffer the buffer to write to MDB_val
* @param ptr the pointer to the MDB_val
* @param ptrAddr the address of the MDB_val pointer
* @return the buffer for MDB_val
*/
protected abstract T out(T buffer, Pointer ptr, long ptrAddr);
/**
* Create a new {@link KeyVal} to hold pointers for this buffer proxy.
*
* @return a non-null key value holder
*/
final KeyVal keyVal() {
return new KeyVal<>(this);
}
}