Page History

...

The framework leverages the try-with-resources syntax to deliver exclusive ByteBuffer access in lexical blocks. The ByteBufferSharing class provides a couple open() methods (one of which supports timeout). These methods return an AutoCloseable "resource", suitable for assignment in a try-with-resources variable declaration. The Java language guarantees that close() will be called on such a resource when the lexical block is left (either through normal program flow or exception). The framework leverages that close() call as a signal to release locks and reduce reference counts.

These are the key interfaces used by clients of the framework:

@startuml
interface AutoCloseable {
void close()
}
interface ByteBufferSharing extends AutoCloseable {
ByteBuffer getBuffer()
ByteBuffer expandWriteBufferIfNeeded(int newCapacity)
ByteBuffer expandReadBufferIfNeeded(int newCapacity)
}

class ByteBufferVendor {
ByteBufferVendor(ByteBuffer bufferArg, BufferType bufferType, BufferPool bufferPool)
ByteBufferSharing open()
ByteBufferSharing open(long time, TimeUnit unit)
void destruct()
}

ByteBufferVendor .. ByteBuffer : derived\nassociation
@enduml

more

...

@enduml

In the next section we'll describe some framework internals.

Internals

The ByteBufferSharingInternalImpl class (a private, static internal class of ByteBufferVendor) is the main implementation of the "resource" class just mentioned. It implements AutoCloseable so it's usable as a resource in try-with-resources. It also implements a public interface, ByteBufferSharing, for use by clients within a try-with-resources block. It's this interface that a user of ByteBuffers will be most interested in:

ByteBuffer getBuffer()
ByteBuffer expandWriteBufferIfNeeded(int newCapacity)
ByteBuffer expandReadBufferIfNeeded(int newCapacity)

The first, obviously, is used to get the ByteBuffer. In the context of try-with-resources, you have exclusive access to the ByteBuffer so you needn't worry about other threads preempting you.

The other two methods are for expanding the ByteBuffer.

The next class diagram (below) expands on the client view depicted in the first diagram. The dotted association between ByteBufferVendor and ByteBuffer is labeled "derived association". That's meant to convey the fact that the whole point of the vendor is that it mediates access to a ByteBuffer. In UML terms, there is a derived association between the two, even though you won't see an explicit (direct) object reference in the code.

@startuml
interface AutoCloseable {
void close()
}
interface ByteBufferSharing extends AutoCloseable {
ByteBuffer getBuffer()
ByteBuffer expandWriteBufferIfNeeded(int newCapacity)
ByteBuffer expandReadBufferIfNeeded(int newCapacity)
}

class ByteBufferVendor {
ByteBufferVendor(ByteBuffer bufferArg, BufferType bufferType, BufferPool bufferPool)
ByteBufferSharing open()
ByteBufferSharing open(long time, TimeUnit unit)
void destruct()
}

interface ByteBufferVendor.ByteBufferSharingInternal extends ByteBufferSharing {
void releaseBuffer()
}
class ByteBufferVendor.ByteBufferSharingInternalImpl implements ByteBufferVendor.ByteBufferSharingInternal {}

ByteBufferVendor "sharing" *-- ByteBufferVendor.ByteBufferSharingInternal
ByteBufferVendor "lock" *-- ReentrantLock
ByteBufferVendor "isDestructed" *-- AtomicBoolean
ByteBufferVendor "counter" *-- AtomicInteger

ByteBufferVendor.ByteBufferSharingInternalImpl "buffer\n0..1" --> "1" ByteBuffer
ByteBufferVendor.ByteBufferSharingInternalImpl "bufferPool\n*" --> "1" BufferPool
ByteBufferVendor.ByteBufferSharingInternalImpl "bufferType\n*" --> "1" BufferType

ByteBufferVendor .. ByteBuffer : derived\nassociation
@enduml

The ByteBufferSharingInternalImpl class (a private, static internal class of ByteBufferVendor) is the main implementation of the "resource" class just mentioned. It implements AutoCloseable so it's usable as a resource in try-with-resources. It also implements a public interface, ByteBufferSharing, for use by clients within a try-with-resources block. It's this interface that a user of ByteBuffers will be most interested in:

ByteBuffer getBuffer()
ByteBuffer expandWriteBufferIfNeeded(int newCapacity)
ByteBuffer expandReadBufferIfNeeded(int newCapacity)

The first, obviously, is used to get the ByteBuffer. In the context of try-with-resources, you have exclusive access to the ByteBuffer so you needn't worry about other threads preempting you.

The other two methods are for expanding the ByteBuffer.

...

Following the Rules

A "resource" object returned from a ByteBufferSharing open() must be assigned in a try-with-resources variable declaration.

...