Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*-
   * See the file LICENSE for redistribution information.
   *
   * Copyright (c) 2002, 2013 Oracle and/or its affiliates.  All rights reserved.
   *
   */
  
  package com.sleepycat.je;
  
 
Encodes database key and data items as a byte array.

Storage and retrieval for the Database and Cursor methods are based on key/data pairs. Both key and data items are represented by DatabaseEntry objects. Key and data byte arrays may refer to arrays of zero length up to arrays of essentially unlimited length.

The DatabaseEntry class provides simple access to an underlying object whose elements can be examined or changed. DatabaseEntry objects can be subclassed, providing a way to associate with it additional data or references to other structures.

Access to DatabaseEntry objects is not re-entrant. In particular, if multiple threads simultaneously access the same DatabaseEntry object using Database or Cursor methods, the results are undefined.

DatabaseEntry objects may be used in conjunction with the object mapping support provided in the com.sleepycat.bind package.

Input and Output Parameters

DatabaseEntry objects are used for both input data (when writing to a database or specifying a search parameter) and output data (when reading from a database). For certain methods, one parameter may be an input parameter and another may be an output parameter. For example, the Database.get(com.sleepycat.je.Transaction,com.sleepycat.je.DatabaseEntry,com.sleepycat.je.DatabaseEntry,com.sleepycat.je.LockMode) method has an input key parameter and an output data parameter. The documentation for each method describes whether its parameters are input or output parameters.

For DatabaseEntry input parameters, the caller is responsible for initializing the data array of the DatabaseEntry. For DatabaseEntry output parameters, the method called will initialize the data array.

Also note that for DatabaseEntry output parameters, the method called will always allocate a new byte array. The byte array specified by the caller will not be used. Therefore, after calling a method that returns output parameters, the application can safely keep a reference to the byte array returned by getData() without danger that the array will be overwritten in a subsequent call.

Offset and Size Properties

By default the Offset property is zero and the Size property is the length of the byte array. However, to allow for optimizations involving the partial use of a byte array, the Offset and Size may be set to non-default values.

For DatabaseEntry output parameters, the Size will always be set to the length of the byte array and the Offset will always be set to zero.

However, for DatabaseEntry input parameters the Offset and Size are set to non-default values by the built-in tuple and serial bindings. For example, with a tuple or serial binding the byte array is grown dynamically as data is output, and the Size is set to the number of bytes actually used. For a serial binding, the Offset is set to a non-zero value in order to implement an optimization having to do with the serialization stream header.

Therefore, for output DatabaseEntry parameters the application can assume that the Offset is zero and the Size is the length of the byte array. However, for input DatabaseEntry parameters the application should not make this assumption. In general, it is safest for the application to always honor the Size and Offset properties, rather than assuming they have default values.

Partial Offset and Length Properties

By default the specified data (byte array, offset and size) corresponds to the full stored key or data item. Optionally, the Partial property can be set to true, and the PartialOffset and PartialLength properties are used to specify the portion of the key or data item to be read or written. For details, see the setPartial(int,int,boolean) method.

Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method, nor will they every be set by bindings. Therefore, the application can assume that the Partial properties are not set, unless the application itself sets them explicitly.

See Using Partial DatabaseEntry Parameters for more information.

 
 public class DatabaseEntry implements Serializable {
    private static final long serialVersionUID = 1L;
    /* Currently, JE stores all data records as byte array */
    private byte[] data;
    private int dlen = 0;
    private int doff = 0;
    private int offset = 0;
    private int size = 0;
    private boolean partial = false;
    /* FindBugs - ignore not "final" since a user can set this. */
    

Hidden:
The maximum number of bytes to show when toString() is called.
    public static int MAX_DUMP_BYTES = 100;

    
Returns all the attributes of the database entry in text form, including the underlying data. The maximum number of bytes that will be formatted is taken from the static variable DatabaseEntry.MAX_DUMP_BYTES, which defaults to 100. MAX_DUMP_BYTES may be changed by an application if it wishes to cause more bytes to be formatted.
    @Override
    public String toString() {
	StringBuilder sb = new StringBuilder("<DatabaseEntry");
        if () {
            sb.append(" partial=\"true");
            sb.append("\" doff=\"").append();
            sb.append("\" dlen=\"").append();
            sb.append("\"");
        }
	sb.append(" offset=\"").append();
	sb.append("\" size=\"").append();
	sb.append("\" data=\"").append(dumpData());
	if (( - 1) > ) {
	    sb.append(" ... ").append(( - ) +
				      " bytes not shown ");
	}
	sb.append("\"/>");
	return sb.toString();
    }
    /*
     * Constructors
     */

    
Constructs a DatabaseEntry with null data. The offset and size are set to zero.
    public DatabaseEntry() {
    }

    
Constructs a DatabaseEntry with a given byte array. The offset is set to zero; the size is set to the length of the array, or to zero if null is passed.

Parameters:
data Byte array wrapped by the DatabaseEntry.
    public DatabaseEntry(byte[] data) {
        this. = data;
        if (data != null) {
            this. = data.length;
        }
    }

    
Constructs a DatabaseEntry with a given byte array, offset and size.

Parameters:
data Byte array wrapped by the DatabaseEntry.
offset Offset in the first byte in the byte array to be included.
size Number of bytes in the byte array to be included.
    public DatabaseEntry(byte[] dataint offsetint size) {
        this. = data;
        this. = offset;
        this. = size;
    }
    /*
     * Accessors
     */

    
Returns the byte array.

For a DatabaseEntry that is used as an output parameter, the byte array will always be a newly allocated array. The byte array specified by the caller will not be used and may be null.

Returns:
The byte array.
    public byte[] getData() {
        return ;
    }

    
Sets the byte array. The offset is set to zero; the size is set to the length of the array, or to zero if null is passed.

Parameters:
data Byte array wrapped by the DatabaseEntry.
    public void setData(byte[] data) {
	this. = data;
         = 0;
	 = (data == null) ? 0 : data.length;
    }

    
Sets the byte array, offset and size.

Parameters:
data Byte array wrapped by the DatabaseEntry.
offset Offset in the first byte in the byte array to be included.
size Number of bytes in the byte array to be included.
    public void setData(byte[] dataint offsetint size) {
	this. = data;
        this. = offset;
        this. = size;
    }

    
Configures this DatabaseEntry to read or write partial records.

Do partial retrieval or storage of an item. If the calling application is doing a retrieval, length bytes specified by dlen, starting at the offset set by doff bytes from the beginning of the retrieved data record are returned as if they comprised the entire record. If any or all of the specified bytes do not exist in the record, the get is successful, and any existing bytes are returned.

For example, if the data portion of a retrieved record was 100 bytes, and a partial retrieval was done using a DatabaseEntry having a partial length of 20 and a partial offset of 85, the retrieval would succeed and the retrieved data would be the last 15 bytes of the record.

If the calling application is storing an item, length bytes specified by dlen, starting at the offset set by doff bytes from the beginning of the specified key's data item are replaced by the data specified by the DatabaseEntry. If the partial length is smaller than the data, the record will grow; if the partial length is larger than the data, the record will shrink. If the partial offset is greater than the length of the data, the record will be extended using zero bytes as necessary, and the store will succeed.

It is an error to specify a partial key when performing a put operation of any kind.

It is an error to attempt a partial store using the Database.put(com.sleepycat.je.Transaction,com.sleepycat.je.DatabaseEntry,com.sleepycat.je.DatabaseEntry) method in a database that supports duplicate records. Partial stores in databases supporting duplicate records must be done using a cursor method.

Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.

Parameters:
doff The offset of the partial record being read or written by the application, in bytes.
dlen The byte length of the partial record being read or written by the application, in bytes.
partial Whether this DatabaseEntry is configured to read or write partial records.
    public void setPartial(int doffint dlenboolean partial) {
        setPartialOffset(doff);
        setPartialLength(dlen);
        setPartial(partial);
    }

    
Returns the byte length of the partial record being read or written by the application, in bytes.

Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.

Returns:
The byte length of the partial record being read or written by the application, in bytes.
See also:
setPartial(int,int,boolean)
    public int getPartialLength() {
        return ;
    }

    
Sets the byte length of the partial record being read or written by the application, in bytes.

Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.

Parameters:
dlen The byte length of the partial record being read or written by the
See also:
setPartial(int,int,boolean)
    public void setPartialLength(int dlen) {
        this. = dlen;
    }

    
Returns the offset of the partial record being read or written by the application, in bytes.

Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.

Returns:
The offset of the partial record being read or written by the application, in bytes.
See also:
setPartial(int,int,boolean)
    public int getPartialOffset() {
        return ;
    }

    
Sets the offset of the partial record being read or written by the application, in bytes.

Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.

Parameters:
doff The offset of the partial record being read or written by the application, in bytes.
See also:
setPartial(int,int,boolean)
    public void setPartialOffset(int doff) {
        this. = doff;
    }

    
Returns whether this DatabaseEntry is configured to read or write partial records.

Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.

Returns:
Whether this DatabaseEntry is configured to read or write partial records.
See also:
setPartial(int,int,boolean)
    public boolean getPartial() {
        return ;
    }

    
Configures this DatabaseEntry to read or write partial records.

Note that the Partial properties are set only by the caller. They will never be set by a Database or Cursor method.

Parameters:
partial Whether this DatabaseEntry is configured to read or write partial records.
See also:
setPartial(int,int,boolean)
    public void setPartial(boolean partial) {
        this. = partial;
    }

    
Returns the byte offset into the data array.

For a DatabaseEntry that is used as an output parameter, the offset will always be zero.

Returns:
Offset in the first byte in the byte array to be included.
    public int getOffset() {
        return ;
    }

    
Sets the byte offset into the data array. ArrayIndexOutOfBoundsException if the data, offset, and size parameters refer to elements of the data array which do not exist. Note that this exception will not be thrown by setSize() or setOffset(), but will be thrown by varous JE methods if "this" is inconsistent and is used as an input parameter to those methods. It is the caller's responsibility to ensure that size, offset, and data.length are consistent.

Parameters:
offset Offset in the first byte in the byte array to be included.
    public void setOffset(int offset) {
        this. = offset;
    }

    
Returns the byte size of the data array.

For a DatabaseEntry that is used as an output parameter, the size will always be the length of the data array.

Returns:
Number of bytes in the byte array to be included.
    public int getSize() {
        return ;
    }

    
Sets the byte size of the data array. ArrayIndexOutOfBoundsException if the data, offset, and size parameters refer to elements of the data array which do not exist. Note that this exception will not be thrown by setSize() or setOffset(), but will be thrown by varous JE methods if "this" is inconsistent and is used as an input parameter to those methods. It is the caller's responsibility to ensure that size, offset, and data.length are consistent.

Parameters:
size Number of bytes in the byte array to be included.
    public void setSize(int size) {
        this. = size;
    }

    
Dumps the data as a byte array, for tracing purposes
    String dumpData() {
	    (KeyRange.getByteArray(this));
    }

    
Compares the data of two entries for byte-by-byte equality.

In either entry, if the offset is non-zero or the size is not equal to the data array length, then only the data bounded by these values is compared. The data array length and offset need not be the same in both entries for them to be considered equal.

If the data array is null in one entry, then to be considered equal both entries must have a null data array.

If the partial property is set in either entry, then to be considered equal both entries must have the same partial properties: partial, partialOffset and partialLength.

    @Override
    public boolean equals(Object o) {
        if (!(o instanceof DatabaseEntry)) {
            return false;
        }
        DatabaseEntry e = (DatabaseEntryo;
        if ( || e.partial) {
            if ( != e.partial ||
                 != e.dlen ||
                 != e.doff) {
                return false;
            }
        }
        if ( == null && e.data == null) {
            return true;
        }
        if ( == null || e.data == null) {
            return false;
        }
        if ( != e.size) {
            return false;
        }
        for (int i = 0; i < i += 1) {
            if ([ + i] != e.data[e.offset + i]) {
                return false;
            }
        }
        return true;
    }

    
Returns a hash code based on the data value.
    @Override
    public int hashCode() {
        int hash = 0;
        if ( != null) {
            for (int i = 0; i < i += 1) {
                hash += [ + i];
            }
        }
        return hash;
    }
New to GrepCode? Check out our FAQ X