ifs.fnd.buffer

Interface Buffer

All Superinterfaces:

java.lang.Cloneable, java.io.Serializable

All Known Implementing Classes:

StandardBuffer

public interface Buffer
extends java.io.Serializable, java.lang.Cloneable

A Buffer is a collection of items. It has an optional header that describes its type and/or contents. Items can be referenced by name or by position.

An Item may have a compound value that contains another Buffer. Buffers can be nested to arbitrary level. Leafs of a Buffer tree structure are always simple values like String or Integer, so Buffers can be easily serialized to a byte or character stream.

More formally a buffer can represent any data structure that meets the following BNF definition:

     Buffer ::= [Header] {Item}
     Item   ::= [Name] [Type] [Status] Value
     Value  ::= String | Integer | Date | Buffer

  where

     [X] means 0 or 1 occurrences of X, and
     {X} means 0, 1 or many occurrences of X

A Buffer can contain meta-data (name and type of each item in the buffer structure), data (value of each item), or both.

A Buffer can have many String representations, which are created by BufferFormatters.

WRITE access to the Buffer:

The following method appends a specified Item to the end of the item list in this Buffer and returns the position of the newly created item. This may lead to duplicate item names.

     public int addItem( Item item );

The following methods create and append a new Item to the end of the item list in this Buffer and returns the position of the newly created item. This may lead to duplicate item names.

     public int addItem( String itemName, XXX value );

  where XXX is one of:
     Buffer, String, Int, ... (a value of an item)

READ access to the Buffer:

The following methods return the indexed item or the first occurrence of the named item. They throw an exception or return a default value, if such item does not exist.

     public XXX getXXX( int position ); // throws RuntimeException
     public XXX getXXX( String itemName ) throws ItemNotFoundException;
     public XXX getXXX( String itemName, XXX default_value );

  where XXX is one of:

     Item (an item itself) or
     Buffer, String, Int, ... (a value of an item)

Method Summary

Modifier and Type	Method and Description
int	addItem(Item item) Append a specified Item to the end of the item list in this Buffer.
int	addItem(java.lang.String itemName, Buffer value) Create and append a new Item to this buffer.
int	addItem(java.lang.String itemName, int value) Create and append a new Item to this buffer.
int	addItem(java.lang.String itemName, java.lang.Object value) Create and append a new Item to this buffer.
int	addItem(java.lang.String itemName, java.lang.String value) Create and append a new Item to this buffer.
void	clear() Clear the contents of this buffer.
java.lang.Object	clone() Clone this Buffer.
int	countItems() Return the number of items collected in this Buffer.
int	countItems(java.lang.String name) Return the number of items with the specified name.
boolean	equals(java.lang.Object obj) Compares this buffer to another one.
Item	findItem(java.lang.String itemName) Find a named Item inthis Buffer.
void	freeze() Freezes this buffer.
Buffer	getBuffer(int position) Get the value of the item at the specified position.
Buffer	getBuffer(java.lang.String itemName) Get the value of the item with the specified name.
Buffer	getBuffer(java.lang.String itemName, Buffer defaultValue) Get the value of the item with the specified name.
java.lang.String	getHeader() Get the header of this Buffer.
int	getInt(int position) Get the value of the item at the specified position.
int	getInt(java.lang.String itemName) Get the value of the item with the specified name.
int	getInt(java.lang.String itemName, int defaultValue) Get the value of the item with the specified name.
Item	getItem(int position) Get the item at the specified position.
Item	getItem(java.lang.String itemName) Get the item with the specified name.
Item	getItem(java.lang.String itemName, Item defaultValue) Get the item with the specified name.
int	getItemPosition(java.lang.String itemName) Get the position of the first occurrence of a named Item.
java.lang.Object	getObject(int position) Get the value of the item at the specified position.
java.lang.Object	getObject(java.lang.String itemName) Get the value of the item with the specified name.
java.lang.Object	getObject(java.lang.String itemName, java.lang.Object defaultValue) Get the value of the item with the specified name.
java.lang.String	getString(int position) Get the value of the item at the specified position.
java.lang.String	getString(java.lang.String itemName) Get the value of the item with the specified name.
java.lang.String	getString(java.lang.String itemName, java.lang.String defaultValue) Get the value of the item with the specified name.
int	hashCode() Compute the hash code for this Buffer
int	insertItem(Item item, int position) Insert a specified Item at the specified position (0,1, ...) in the item list.
boolean	isFrozen() Indicates if this buffer is frozen.
BufferIterator	iterator() Return an iterator over all items in this Buffer.
Buffer	newInstance() Return a new (empty) instance of the same class as this Buffer
Item	newItem() Return a new instance of Item
void	removeItem(int position) Remove the Item at a specified position (0,1, ...) in this Buffer
void	removeItem(java.lang.String name) Remove the named item from the item list in this Buffer.
void	removeItems() Remove all items from this Buffer
void	setHeader(java.lang.String header) Set the header of this Buffer.
int	setItem(java.lang.String itemName, int value) Mofify the first occurence of a named item, or create a new item, if such item does not exist.
int	setItem(java.lang.String itemName, java.lang.String value) Mofify the first occurence of a named item, or create a new item, if such item does not exist.
void	unfreeze() Un-freezes this buffer.

Method Detail

setHeader

void setHeader(java.lang.String header)

Set the header of this Buffer.

Parameters:

header - string describing the contents of this buffer

getHeader

java.lang.String getHeader()

Get the header of this Buffer.

Returns:

a string describing the contents of this buffer

countItems

int countItems()

Return the number of items collected in this Buffer.

Returns:

the number of items collected in this Buffer.

countItems

int countItems(java.lang.String name)

Return the number of items with the specified name.

Parameters:

name - item name

Returns:

the number of items with the specified name collected in this Buffer.

iterator

BufferIterator iterator()

Return an iterator over all items in this Buffer.

Returns:

an instance of BufferIterator

addItem

int addItem(Item item)

Append a specified Item to the end of the item list in this Buffer. The operation may lead to duplicate item names.

Parameters:

item - an item to add to this buffer

Returns:

the zero-based index of the added item.

addItem

int addItem(java.lang.String itemName,
            java.lang.Object value)

Create and append a new Item to this buffer. The item will be placed at the end of the item list in this Buffer, which may lead to duplicate item names.

Parameters:

itemName - item name

value - item value

Returns:

the position of the newly created item (0,1, ...).

addItem

int addItem(java.lang.String itemName,
            Buffer value)

Create and append a new Item to this buffer. The item will be placed at the end of the item list in this Buffer, which may lead to duplicate item names.

Parameters:

itemName - item name

value - item value

Returns:

the position of the newly created item (0,1, ...).

addItem

int addItem(java.lang.String itemName,
            java.lang.String value)

Create and append a new Item to this buffer. The item will be placed at the end of the item list in this Buffer, which may lead to duplicate item names.

Parameters:

itemName - item name

value - item value

Returns:

the position of the newly created item (0,1, ...).

addItem

int addItem(java.lang.String itemName,
            int value)

Create and append a new Item to this buffer. The item will be placed at the end of the item list in this Buffer, which may lead to duplicate item names.

Parameters:

itemName - item name

value - item value

Returns:

the position of the newly created item (0,1, ...).

insertItem

int insertItem(Item item,
               int position)

Insert a specified Item at the specified position (0,1, ...) in the item list. This may lead to duplicate item names. If the specified position is outside range, then the item will be added at the end of the item list.

Parameters:

item - the item to insert

position - a zero-bassed index

Returns:

the position of the inserted item.

setItem

int setItem(java.lang.String itemName,
            java.lang.String value)

Mofify the first occurence of a named item, or create a new item, if such item does not exist.

Parameters:

itemName - item name

value - item value

Returns:

the item's position in the buffer (0,1, ...).

setItem

int setItem(java.lang.String itemName,
            int value)

Mofify the first occurence of a named item, or create a new item, if such item does not exist.

Parameters:

itemName - item name

value - item value

Returns:

the item's position in the buffer (0,1, ...).

getItemPosition

int getItemPosition(java.lang.String itemName)

Get the position of the first occurrence of a named Item.

Parameters:

itemName - item name

Returns:

the item position or -1 if such item does not exist.

getItem

Item getItem(int position)

Get the item at the specified position.

Parameters:

position - a zero-based index of an existing item in the buffer

Returns:

the item at given index

getItem

Item getItem(java.lang.String itemName)
      throws ItemNotFoundException

Get the item with the specified name.

Parameters:

itemName - item name

Returns:

the found item

Throws:

ItemNotFoundException - if the specified item does not exist

getItem

Item getItem(java.lang.String itemName,
             Item defaultValue)

Get the item with the specified name.

Parameters:

itemName - item name

defaultValue - the default value (possibly null)

Returns:

the named item, or the default value if the named item does not exist

getString

java.lang.String getString(int position)

Get the value of the item at the specified position.

Parameters:

position - an index to an existing item in the buffer

Returns:

the String value of the item at given index

getString

java.lang.String getString(java.lang.String itemName)
                    throws ItemNotFoundException

Get the value of the item with the specified name.

Parameters:

itemName - item name

Returns:

the String value of the named item

Throws:

ItemNotFoundException - if the specified item does not exist

getString

java.lang.String getString(java.lang.String itemName,
                           java.lang.String defaultValue)

Get the value of the item with the specified name.

Parameters:

itemName - item name

defaultValue - the default value (possibly null)

Returns:

the String value of the named item, or the default value if the named item does not exist

getInt

int getInt(int position)

Get the value of the item at the specified position.

Parameters:

position - an index to an existing item in the buffer

Returns:

the integer value of the item at given index

getInt

int getInt(java.lang.String itemName)
    throws ItemNotFoundException

Get the value of the item with the specified name.

Parameters:

itemName - item name

Returns:

the integer value of the named item

Throws:

ItemNotFoundException - if the specified item does not exist

getInt

int getInt(java.lang.String itemName,
           int defaultValue)

Get the value of the item with the specified name.

Parameters:

itemName - item name

defaultValue - the default value

Returns:

the integer value of the named item, or the default value if the named item does not exist

getObject

java.lang.Object getObject(int position)

Get the value of the item at the specified position.

Parameters:

position - an index of an existing item in the buffer

Returns:

the Object being the value of the item at given index

getObject

java.lang.Object getObject(java.lang.String itemName)
                    throws ItemNotFoundException

Get the value of the item with the specified name.

Parameters:

itemName - item name

Returns:

the Object being the value of the named item

Throws:

ItemNotFoundException - if the specified item does not exist

getObject

java.lang.Object getObject(java.lang.String itemName,
                           java.lang.Object defaultValue)

Get the value of the item with the specified name.

Parameters:

itemName - item name

defaultValue - the default value (possibly null)

Returns:

the Object being the value of the named item, or the default value if the named item does not exist

getBuffer

Buffer getBuffer(int position)

Get the value of the item at the specified position.

Parameters:

position - an index to an existing item in the buffer

Returns:

the Buffer being the value of the item at given index

getBuffer

Buffer getBuffer(java.lang.String itemName)
          throws ItemNotFoundException

Get the value of the item with the specified name.

Parameters:

itemName - item name

Returns:

the Buffer being the value of the named item

Throws:

ItemNotFoundException - if the specified item does not exist

getBuffer

Buffer getBuffer(java.lang.String itemName,
                 Buffer defaultValue)

Get the value of the item with the specified name.

Parameters:

itemName - item name

defaultValue - the default value (possibly null)

Returns:

the Buffer being the value of the named item, or the default value if the named item does not exist

removeItem

void removeItem(java.lang.String name)

Remove the named item from the item list in this Buffer. This aplies only to the first occurence, if there are many items with the specified name. If the specified item does not exist the method does nothing.

Parameters:

name - the name of an item

removeItem

void removeItem(int position)

Remove the Item at a specified position (0,1, ...) in this Buffer

Parameters:

position - zero-based index of an existing item

removeItems

void removeItems()

Remove all items from this Buffer

findItem

Item findItem(java.lang.String itemName)

Find a named Item inthis Buffer. The name can contain "/"-operator, for example "A/B/C" points to item "C" in sub-buffer "B" of sub-buffer "A" of this buffer.

Parameters:

itemName - item name

Returns:

the found Item, or null if such Item does not exist.

clear

void clear()

Clear the contents of this buffer. The methods removes all items from the buffer, and also clears other instance variables, like for example header.

newInstance

Buffer newInstance()

Return a new (empty) instance of the same class as this Buffer

Returns:

a new, empty instance of Buffer interface

equals

boolean equals(java.lang.Object obj)

Compares this buffer to another one.

Overrides:

equals in class java.lang.Object

Returns:

true if a specified Object is a Buffer and has exactly the same contents as this Buffer

clone

java.lang.Object clone()

Clone this Buffer.

Returns:

a new instance of Buffer with the same contents as this buffer.

hashCode

int hashCode()

Compute the hash code for this Buffer

Overrides:

hashCode in class java.lang.Object

Returns:

an int value representing the contents of this buffer

newItem

Item newItem()

Return a new instance of Item

Returns:

a new instance of Item

isFrozen

boolean isFrozen()

Indicates if this buffer is frozen.

Returns:

true if this buffer is frozen, false otherwise

freeze

void freeze()

Freezes this buffer.

unfreeze

void unfreeze()

Un-freezes this buffer.