Package org.jcsp.util

# Class Buffer

java.lang.Object
org.jcsp.util.Buffer

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `ChannelDataStore`

public class Buffer extends Object implements ChannelDataStore, Serializable
This is used to create a buffered object channel that never loses data.

## Description

`Buffer` is an implementation of `ChannelDataStore` that yields a blocking FIFO buffered semantics for a channel. See the `static` construction methods of `Channel` (`Channel.one2one(org.jcsp.util.ChannelDataStore)` etc.).

The `getState` method returns `EMPTY`, `NONEMPTYFULL` or `FULL` according to the state of the buffer.

Author:
  P.D. Austin
See Also:
  - `ZeroBuffer`
  - `OverWriteOldestBuffer`
  - `OverWritingBuffer`
  - `OverFlowingBuffer`
  - `InfiniteBuffer`
  - `Channel`
  - Serialized Form

## Field Summary

### Fields inherited from interface org.jcsp.util.ChannelDataStore

`EMPTY, FULL, NONEMPTYFULL`

## Constructor Summary

Constructors
Constructor
Description
`Buffer(int size)`
Construct a new `Buffer` with the specified size.

## Method Summary

Modifier and Type
Method
Description
`Object`
`clone()`
Returns a new (and `EMPTY`) `Buffer` with the same creation parameters as this one.
`void`
`endGet()`
Removes the oldest object from the buffer.
`Object`
`get()`
Returns the oldest `Object` from the `Buffer` and removes it.
`int`
`getState()`
Returns the current state of the `Buffer`.
`void`
`put(Object value)`
Puts a new `Object` into the `Buffer`.
`void`
`removeAll()`
Deletes all items in the buffer, leaving it empty.
`Object`
`startGet()`
Returns the oldest object from the buffer but does not remove it.

### Methods inherited from class java.lang.Object

`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### Buffer

public Buffer(int size)
Construct a new `Buffer` with the specified size.

Parameters:
  `size` - the number of Objects the Buffer can store.
Throws:
  `BufferSizeError` - if `size` is negative. Note: no action should be taken to `try`/`catch` this exception - application code generating it is in error and needs correcting.

## Method Details

### get

public Object get()
Returns the oldest `Object` from the `Buffer` and removes it.

Pre-condition: `getState` must not currently return `EMPTY`.

Specified by:
  `get` in interface `ChannelDataStore`
Returns:
  the oldest `Object` from the `Buffer`

### startGet

public Object startGet()
Returns the oldest object from the buffer but does not remove it. Pre-condition: `getState` must not currently return `EMPTY`.

Specified by:
  `startGet` in interface `ChannelDataStore`
Returns:
  the oldest `Object` from the `Buffer`
See Also:
  - `ChannelDataStore.endGet()`

### endGet

public void endGet()
Removes the oldest object from the buffer.

Specified by:
  `endGet` in interface `ChannelDataStore`
See Also:
  - `ChannelDataStore.startGet()`

### put

public void put(Object value)
Puts a new `Object` into the `Buffer`.

Pre-condition: `getState` must not currently return `FULL`.

Specified by:
  `put` in interface `ChannelDataStore`
Parameters:
  `value` - the Object to put into the Buffer

### getState

public int getState()
Returns the current state of the `Buffer`.

Specified by:
  `getState` in interface `ChannelDataStore`
Returns:
  the current state of the `Buffer` (`EMPTY`, `NONEMPTYFULL` or `FULL`)

### clone

public Object clone()
Returns a new (and `EMPTY`) `Buffer` with the same creation parameters as this one.

Note: Only the size and structure of the `Buffer` is cloned, not any stored data.

Specified by:
  `clone` in interface `ChannelDataStore`
Overrides:
  `clone` in class `Object`
Returns:
  the cloned instance of this `Buffer`

### removeAll

public void removeAll()
Description copied from interface: `ChannelDataStore`
Deletes all items in the buffer, leaving it empty.

Specified by:
  `removeAll` in interface `ChannelDataStore`