bibliothek.gui.dock.station.support
Class PlaceholderMap

java.lang.Object
  bibliothek.gui.dock.station.support.PlaceholderMap

public class PlaceholderMap
extends Object

A data structure designed to store and retrieve placeholder information persistently. This data structure basically is a map with a restricted set of types that are allowed to be stored. This map uses arrays of Paths as PlaceholderMap.Keys, there are two modes how to use the keys:

• If using shared keys, this map will use the equals method to compare keys
• If using non-shared keys, this map will use the == operator to compare keys

This data structure can work together with a PlaceholderStrategy to automatically delete entries that are no longer valid.

Author:

Benjamin Sigg

Nested Class Summary

static interface

PlaceholderMap.Key A key is a set of Paths, it is used to identify entries in a PlaceholderMap.

Constructor Summary

PlaceholderMap(DataInputStream in, PlaceholderStrategy strategy)
Creates a new map reading the content of the map directly from in.

PlaceholderMap(Path format, int version)
Creates a new map.

PlaceholderMap(XElement in, PlaceholderStrategy strategy)
Creates a new map reading the content of the map directly from in.

Method Summary

void	add(PlaceholderMap.Key placeholder) Adds the placeholder placeholder to this map.
boolean	contains(PlaceholderMap.Key placeholder, String key) Tells whether key exists for placeholder.
PlaceholderMap	copy() Creates a deep copy of this map.
PlaceholderMap.Key	copyKey(PlaceholderMap.Key key) Creates a copy of key.
PlaceholderMap	filter(PlaceholderStrategy strategy) May return this or a copy of this PlaceholderMap to which strategy was applied.
Object	get(PlaceholderMap.Key placeholder, String key) Gets the data that is stored under key.
Object[]	getArray(PlaceholderMap.Key placeholder, String key) Gets the map that is stored under key
boolean	getBoolean(PlaceholderMap.Key placeholder, String key) Gets the boolean that is stored under key
double	getDouble(PlaceholderMap.Key placeholder, String key) Gets the double that is stored under key
Path	getFormat() Gets the format of this map, the meaning of the format depends on the client.
int	getInt(PlaceholderMap.Key placeholder, String key) Gets the integer that is stored under key
String[]	getKeys(PlaceholderMap.Key placeholder) Gets all keys that are in use for placeholder in the order they were first used to put an object into this map.
long	getLong(PlaceholderMap.Key placeholder, String key) Gets the long that is stored under key
PlaceholderMap	getMap(PlaceholderMap.Key placeholder, String key) Gets the map that is stored under key
Path	getPath(PlaceholderMap.Key placeholder, String key) Gets the Path that is stored under key
PlaceholderMap.Key[]	getPlaceholders() Gets all placeholders that are known to this map in the order they were added to this map.
PlaceholderStrategy	getPlaceholderStrategy() Gets the strategy that is observed for removing invalid placeholders.
String	getString(PlaceholderMap.Key placeholder, String key) Gets the string that is stored under key
int	getVersion() Gets the version of the format used in this map.
boolean	isEmpty() Tells whether this map is completely empty.
PlaceholderMap.Key	newKey(Path... placeholders) Creates a new shared key for any set of placeholders.
PlaceholderMap.Key	newKey(String anchor, Path... placeholders) Creates a new shared key for any set of placeholders.
PlaceholderMap.Key	newUniqueKey(Path... placeholders) Creates a new non-shared key for any set of placeholders.
PlaceholderMap.Key	newUniqueKey(String anchor, Path... placeholders) Creates a new non-shared key for any set of placeholders.
void	put(PlaceholderMap.Key placeholder, String key, Object value) Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent. It is the clients responsibility not to introduce cycles of object references.
void	putArray(PlaceholderMap.Key placeholder, String key, Object[] value) Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.
void	putBoolean(PlaceholderMap.Key placeholder, String key, boolean value) Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.
void	putDouble(PlaceholderMap.Key placeholder, String key, double value) Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.
void	putInt(PlaceholderMap.Key placeholder, String key, int value) Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.
void	putLong(PlaceholderMap.Key placeholder, String key, long value) Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.
void	putMap(PlaceholderMap.Key placeholder, String key, PlaceholderMap value) Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.
void	putPath(PlaceholderMap.Key placeholder, String key, Path value) Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.
void	putString(PlaceholderMap.Key placeholder, String key, String value) Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.
void	remove(PlaceholderMap.Key placeholder) Removes placeholder and all information that is associated with placeholder from this map.
Object	remove(PlaceholderMap.Key placeholder, String key) Removes the value that is stored at key.
void	removeAll(Path placeholder, boolean recursive) Removes all occurrences of placeholders.
void	removeAll(Set<Path> placeholders, boolean recursive) Removes all occurrences of all elements of placeholders.
void	setPlaceholderStrategy(PlaceholderStrategy strategy) Sets the strategy that is used to automatically remove invalid placeholders.
String	toString()
void	validate(PlaceholderStrategy strategy, boolean recursive) Using strategy removes all placeholders that are invalid.
void	write(DataOutputStream out) Writes the contents of this map into out.
void	write(XElement out) Writes the contents of this map into out.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PlaceholderMap

public PlaceholderMap(Path format,
                      int version)

Creates a new map.

Parameters:

format - the kind of data stored in this map, the exact meaning depends on the client that is using this map

version - the version of the format, the exact meaning depends on the client that is using this map

PlaceholderMap

public PlaceholderMap(DataInputStream in,
                      PlaceholderStrategy strategy)
               throws IOException

Creates a new map reading the content of the map directly from in.

Parameters:

in - the content

strategy - guard to identify the placeholders which are allowed to be stored, can be null

Throws:

IOException - in case of an I/O error

PlaceholderMap

public PlaceholderMap(XElement in,
                      PlaceholderStrategy strategy)

Creates a new map reading the content of the map directly from in.

Parameters:

in - the content to read

strategy - guard to identify the placeholders which are allowed to be stored, can be null

Method Detail

write

public void write(DataOutputStream out)
           throws IOException

Writes the contents of this map into out.

Parameters:

out - the stream to write into

Throws:

IOException - in case of an I/O error

write

public void write(XElement out)

Writes the contents of this map into out.

Parameters:

out - the element to fill, its attributes will not be modified

copy

public PlaceholderMap copy()

Creates a deep copy of this map.

Returns:

the copy, not null

filter

public PlaceholderMap filter(PlaceholderStrategy strategy)

May return this or a copy of this PlaceholderMap to which strategy was applied. The strategy of the result may or may not be set. This map is not modified by this method.

Parameters:

strategy - the strategy to apply

Returns:

either this or a copy of this map

newKey

public PlaceholderMap.Key newKey(Path... placeholders)

Creates a new shared key for any set of placeholders. The new key will be equal to any key that is generated by this method using the same arguments.

Parameters:

placeholders - the placeholders of the key

Returns:

the new key

newKey

public PlaceholderMap.Key newKey(String anchor,
                                 Path... placeholders)

Creates a new shared key for any set of placeholders. The new key will be equal to any key that is generated by this method using the same arguments.

Parameters:

anchor - if the anchor is set, then this key cannot be automatically deleted. It is the clients responsibility to ensure that no two keys have the same anchor. If two keys have the same anchor, then one of them might override the other one leading to data loss. Can be null.

placeholders - the placeholders of the key

Returns:

the new key

newUniqueKey

public PlaceholderMap.Key newUniqueKey(Path... placeholders)

Creates a new non-shared key for any set of placeholders. The new key will not be equal to any other key but itself.

Parameters:

placeholders - the placeholders of the key

Returns:

the new key

newUniqueKey

public PlaceholderMap.Key newUniqueKey(String anchor,
                                       Path... placeholders)

Creates a new non-shared key for any set of placeholders. The new key will not be equal to any other key but itself.

Parameters:

placeholders - the placeholders of the key

anchor - if the anchor is set, then this key cannot be automatically deleted. It is the clients responsibility to ensure that no two keys have the same anchor. If two keys have the same anchor, then one of them might override the other one leading to data loss. Can be null.

Returns:

the new key

copyKey

public PlaceholderMap.Key copyKey(PlaceholderMap.Key key)

Creates a copy of key.

Parameters:

key - the key to copy

Returns:

the new key

setPlaceholderStrategy

public void setPlaceholderStrategy(PlaceholderStrategy strategy)

Sets the strategy that is used to automatically remove invalid placeholders. This strategy is recursivelly applied to all other PlaceholderMaps that are stored within this map.

Parameters:

strategy - the new strategy, can be null

getPlaceholderStrategy

public PlaceholderStrategy getPlaceholderStrategy()

Gets the strategy that is observed for removing invalid placeholders.

Returns:

the strategy, can be null

validate

public void validate(PlaceholderStrategy strategy,
                     boolean recursive)

Using strategy removes all placeholders that are invalid.

Parameters:

strategy - the strategy for checking the placeholders, a value or null means that all placeholders are valid

recursive - if true then validate(PlaceholderStrategy,boolean) is also called on all sub-maps of this map

removeAll

public void removeAll(Path placeholder,
                      boolean recursive)

Removes all occurrences of placeholders.

Parameters:

placeholder - the placeholder to remove

recursive - if true, this method is called recusively on every sub-map in this map

removeAll

public void removeAll(Set<Path> placeholders,
                      boolean recursive)

Removes all occurrences of all elements of placeholders.

Parameters:

placeholders - the placeholders to remove

recursive - if true, this method is called recusively on every sub-map in this map

getVersion

public int getVersion()

Gets the version of the format used in this map.

Returns:

the version, its meaning depends on the format

getFormat

public Path getFormat()

Gets the format of this map, the meaning of the format depends on the client.

Returns:

the format, not null

add

public void add(PlaceholderMap.Key placeholder)

Adds the placeholder placeholder to this map. Nothing happens if placeholder is already in this map.

Parameters:

placeholder - the new placeholder, not null

remove

public void remove(PlaceholderMap.Key placeholder)

Removes placeholder and all information that is associated with placeholder from this map.

Parameters:

placeholder - the placeholder to clear

getPlaceholders

public PlaceholderMap.Key[] getPlaceholders()

Gets all placeholders that are known to this map in the order they were added to this map.

Returns:

all placeholders

getKeys

public String[] getKeys(PlaceholderMap.Key placeholder)

Gets all keys that are in use for placeholder in the order they were first used to put an object into this map.

Parameters:

placeholder - some placeholder

Returns:

the associated keys, null if placeholder is not known to this map

isEmpty

public boolean isEmpty()

Tells whether this map is completely empty.

Returns:

true if there are no data stored in this map

putString

public void putString(PlaceholderMap.Key placeholder,
                      String key,
                      String value)

Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.

Parameters:

placeholder - the placeholder for which value is stored

key - the unique identifier of the value

value - the new value, not null

putPath

public void putPath(PlaceholderMap.Key placeholder,
                    String key,
                    Path value)

Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.

Parameters:

placeholder - the placeholder for which value is stored

key - the unique identifier of the value

value - the new value, not null

putInt

public void putInt(PlaceholderMap.Key placeholder,
                   String key,
                   int value)

Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.

Parameters:

placeholder - the placeholder for which value is stored

key - the unique identifier of the value

value - the new value

putLong

public void putLong(PlaceholderMap.Key placeholder,
                    String key,
                    long value)

Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.

Parameters:

placeholder - the placeholder for which value is stored

key - the unique identifier of the value

value - the new value

putBoolean

public void putBoolean(PlaceholderMap.Key placeholder,
                       String key,
                       boolean value)

Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.

Parameters:

placeholder - the placeholder for which value is stored

key - the unique identifier of the value

value - the new value

putDouble

public void putDouble(PlaceholderMap.Key placeholder,
                      String key,
                      double value)

Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.

Parameters:

placeholder - the placeholder for which value is stored

key - the unique identifier of the value

value - the new value

putMap

public void putMap(PlaceholderMap.Key placeholder,
                   String key,
                   PlaceholderMap value)

Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.

Parameters:

placeholder - the placeholder for which value is stored

key - the unique identifier of the value

value - the new value, not null

putArray

public void putArray(PlaceholderMap.Key placeholder,
                     String key,
                     Object[] value)

Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.

Parameters:

placeholder - the placeholder for which value is stored

key - the unique identifier of the value

value - the new value, not null. May contain any data type for which this map offers a put-method.

put

public void put(PlaceholderMap.Key placeholder,
                String key,
                Object value)

Stores the value value in this map, adds placeholder if necessary, overrides the value stored at key if existent.
It is the clients responsibility not to introduce cycles of object references.

Parameters:

placeholder - the placeholder for which value is stored

key - the unique identifier of the value

value - the new value, not null

Throws:

IllegalArgumentException - if value is neither String, Integer, Long, Double, Boolean PlaceholderMap nor an array of Objects containing the mentioned data types

remove

public Object remove(PlaceholderMap.Key placeholder,
                     String key)

Removes the value that is stored at key. Note that this method will not remove placeholder from this map even if there is no data left associated with placeholder.

Parameters:

placeholder - the placeholder in whose realm the data is deleted

key - the unique identifier of the removed data

Returns:

the data that was removed, may be null

contains

public boolean contains(PlaceholderMap.Key placeholder,
                        String key)

Tells whether key exists for placeholder.

Parameters:

placeholder - the placeholder in whose realm key should exist

key - the key to search

Returns:

true if there is some data stored

getString

public String getString(PlaceholderMap.Key placeholder,
                        String key)

Gets the string that is stored under key

Parameters:

placeholder - the placeholder in whose realm to search

key - the unique identifier of the searched data

Returns:

the data, not null

Throws:

IllegalArgumentException - if either the value is of the wrong type or missing

getPath

public Path getPath(PlaceholderMap.Key placeholder,
                    String key)

Gets the Path that is stored under key

Parameters:

placeholder - the placeholder in whose realm to search

key - the unique identifier of the searched data

Returns:

the data, not null

Throws:

IllegalArgumentException - if either the value is of the wrong type or missing

getInt

public int getInt(PlaceholderMap.Key placeholder,
                  String key)

Gets the integer that is stored under key

Parameters:

placeholder - the placeholder in whose realm to search

key - the unique identifier of the searched data

Returns:

the data, not null

Throws:

IllegalArgumentException - if either the value is of the wrong type or missing

getLong

public long getLong(PlaceholderMap.Key placeholder,
                    String key)

Gets the long that is stored under key

Parameters:

placeholder - the placeholder in whose realm to search

key - the unique identifier of the searched data

Returns:

the data, not null

Throws:

IllegalArgumentException - if either the value is of the wrong type or missing

getBoolean

public boolean getBoolean(PlaceholderMap.Key placeholder,
                          String key)

Gets the boolean that is stored under key

Parameters:

placeholder - the placeholder in whose realm to search

key - the unique identifier of the searched data

Returns:

the data, not null

Throws:

IllegalArgumentException - if either the value is of the wrong type or missing

getDouble

public double getDouble(PlaceholderMap.Key placeholder,
                        String key)

Gets the double that is stored under key

Parameters:

placeholder - the placeholder in whose realm to search

key - the unique identifier of the searched data

Returns:

the data, not null

Throws:

IllegalArgumentException - if either the value is of the wrong type or missing

getMap

public PlaceholderMap getMap(PlaceholderMap.Key placeholder,
                             String key)

Gets the map that is stored under key

Parameters:

placeholder - the placeholder in whose realm to search

key - the unique identifier of the searched data

Returns:

the data, not null

Throws:

IllegalArgumentException - if either the value is of the wrong type or missing

getArray

public Object[] getArray(PlaceholderMap.Key placeholder,
                         String key)

Gets the map that is stored under key

Parameters:

placeholder - the placeholder in whose realm to search

key - the unique identifier of the searched data

Returns:

the data, not null

Throws:

IllegalArgumentException - if either the value is of the wrong type or missing

get

public Object get(PlaceholderMap.Key placeholder,
                  String key)

Gets the data that is stored under key.

Parameters:

placeholder - the realm in which to search

key - the key of the data

Returns:

the data, may be null

toString

public String toString()

Overrides:

toString in class Object