| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more contributor license |
| * agreements. See the NOTICE file distributed with this work for additional information regarding |
| * copyright ownership. The ASF licenses this file to You 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. |
| */ |
| package org.apache.geode.internal.offheap; |
| |
| import java.io.DataOutput; |
| import java.io.IOException; |
| import java.nio.ByteBuffer; |
| |
| import org.apache.geode.internal.Sendable; |
| import org.apache.geode.internal.cache.CachedDeserializable; |
| import org.apache.geode.internal.offheap.annotations.Retained; |
| import org.apache.geode.internal.offheap.annotations.Unretained; |
| |
| /** |
| * Represents an object stored in the cache. Currently this interface is only used for values stored |
| * in off-heap regions. This interface provides methods that let you read and write the bytes of |
| * addressable memory used to store the bytes of the object. A reference count is used to determine |
| * if the object is still allocated. To increment the count call {@link #retain()}. To decrement the |
| * count call {@link #release()}. At some point in the future it may also be used for values stored |
| * in heap regions. |
| * |
| * @since Geode 1.0 |
| */ |
| public interface StoredObject extends Sendable, CachedDeserializable, Releasable { |
| /** |
| * Returns true if the value stored in this memory chunk is compressed. Returns false if it is |
| * uncompressed. |
| */ |
| boolean isCompressed(); |
| |
| /** |
| * Returns the data stored in this object as a deserialized heap object. If it is not serialized |
| * then the result will be a byte[]. Otherwise the deserialized heap form of the stored object is |
| * returned. |
| * |
| * @return the data stored in this object as a deserialized heap object. |
| */ |
| Object getValueAsDeserializedHeapObject(); |
| |
| /** |
| * Returns the data stored in this object as a heap byte array. If it is not serialized then the |
| * result will only contain the raw bytes stored in this object. Otherwise the serialized heap |
| * form of the stored object is returned. |
| * |
| * @return the data stored in this object as a heap byte array. |
| */ |
| byte[] getValueAsHeapByteArray(); |
| |
| /** |
| * Take all the bytes in the object and write them to the data output as a byte array. If the |
| * StoredObject is not serialized then its raw byte array is sent. But if it is serialized then |
| * the serialized byte array is sent. The corresponding de-serialization will need to call |
| * readByteArray. |
| * |
| * @param out the data output to send this object to |
| */ |
| void sendAsByteArray(DataOutput out) throws IOException; |
| |
| /** |
| * Take all the bytes in the object and write them to the data output as a byte array. If the |
| * StoredObject is not serialized then an exception will be thrown. The corresponding |
| * deserialization will need to call readObject and will get an instance of |
| * VMCachedDeserializable. |
| * |
| * @param out the data output to send this object to |
| */ |
| void sendAsCachedDeserializable(DataOutput out) throws IOException; |
| |
| /** |
| * Call to indicate that this object's memory is in use by the caller. The memory will stay |
| * allocated until {@link #release()} is called. It is ok for a thread other than the one that |
| * called this method to call release. This method is called implicitly at the time the chunk is |
| * allocated. Note: @Retained tells you that "this" is retained by this method. |
| * |
| * @throws IllegalStateException if the max ref count is exceeded. |
| * @return true if we are able to retain this chunk; false if we need to retry |
| */ |
| @Retained |
| boolean retain(); |
| |
| /** |
| * Returns true if this type of StoredObject uses a references count; false otherwise. |
| */ |
| boolean hasRefCount(); |
| |
| /** |
| * Returns the number of users of this memory. If this type of StoredObject does not have a |
| * reference count then -1 is returned. |
| */ |
| int getRefCount(); |
| |
| /** |
| * Returns the address of the memory used to store this object. This address may not be to the |
| * first byte of stored data since the implementation may store some internal data in the first |
| * bytes of the memory. This address can be used with AddressableMemoryManager. |
| */ |
| long getAddress(); |
| |
| /** |
| * Returns the number of bytes of memory used by this object to store an object. This size |
| * includes any bytes used for padding and meta-information. |
| */ |
| int getSize(); |
| |
| /** |
| * Returns the number of bytes of memory used to store the object. This size does not include any |
| * bytes used for padding. |
| */ |
| int getDataSize(); |
| |
| byte readDataByte(int offset); |
| |
| void writeDataByte(int offset, byte value); |
| |
| void readDataBytes(int offset, byte[] bytes); |
| |
| void writeDataBytes(int offset, byte[] bytes); |
| |
| void readDataBytes(int offset, byte[] bytes, int bytesOffset, int size); |
| |
| void writeDataBytes(int offset, byte[] bytes, int bytesOffset, int size); |
| |
| /** |
| * Returns an address that can read data from this StoredObject at the given offset. |
| */ |
| long getAddressForReadingData(int offset, int size); |
| |
| /** |
| * Returns a StoredObject that acts as if its data is our data starting at the given offset and |
| * limited to the given number of bytes. |
| */ |
| StoredObject slice(int offset, int limit); |
| |
| /** |
| * Returns true if our data is equal to other's data; false otherwise. |
| */ |
| boolean checkDataEquals(StoredObject other); |
| |
| /** |
| * Returns true if the given bytes are equal to our data bytes; false otherwise |
| */ |
| boolean checkDataEquals(byte[] serializedObj); |
| |
| /** |
| * Creates and returns a direct ByteBuffer that contains the data of this stored object. Note that |
| * the returned ByteBuffer has a reference to the address of this stored object so it can only be |
| * used while this stored object is retained. |
| * |
| * @return the created direct byte buffer or null if it could not be created. |
| */ |
| @Unretained |
| ByteBuffer createDirectByteBuffer(); |
| |
| /** |
| * Returns true if the data is serialized with PDX |
| */ |
| boolean isSerializedPdxInstance(); |
| |
| /** |
| * Returns a StoredObject that does not cache the heap form. If a StoredObject is going to be kept |
| * around for a while then it is good to call this so that it will not also keep the heap form in |
| * memory. |
| */ |
| StoredObject getStoredObjectWithoutHeapForm(); |
| |
| /** |
| * Return true if the given "o" is reference to off-heap memory. |
| */ |
| static boolean isOffHeapReference(Object o) { |
| return (o instanceof StoredObject) && ((StoredObject) o).hasRefCount(); |
| } |
| } |