com.davisor.data
Class TupleFormat

java.lang.Object
  java.text.Format
      com.davisor.data.TupleFormat

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable

public class TupleFormat

extends java.text.Format

TupleFormat.

TupleFormat is a powerfull locale sensitive formatter and parser for tuple data objects. The formatter provides powerfull tuple member access and formatting capabilities with the help of TupleData data access services, and the whole range of Type framework services.

Introduction

TupleData instances are composite DataValue objects that contain a number of other data values. Each data value has a well formatted string representation, and therefore so does each TupleData instance.

Tuple format instances control the exact string format of TupleData objects. In particular, tuple format tells which tuple data members will appear in the text representation, in which order, how many times, and in which format. Tuple formats may also define constant text segments between the tuple data members, and even fetch values from an external additionalValues map.

Additional values

The formatter supports tuple data additional value mechanism that allows values outside tuple data objects to be included into the string the formatter creates. In particular, the formatter may be given an additional value map with setAdditionalValues(java.util.Map). The formatter will then pass this map to the target tuple data objects when their member values are accessed.

The map is quaranteed to be passed always by reference to allow any changes to the map to affect the formatting. As described by TupleData.get(Object,Map), all map access will also always be synchronized with the map object itself.

Syntax

Tuple formats are defined with tuple format patter strings that have a syntax very similar to standard Java MessageFormat patterns:

 formatPattern := ( [string] "{" formatElement "}" )* [string]

 formatElement := elementKey [ "," elementType ]

 elementType := typeName [ "," typeSpecs ]
 

Constant strings

string components are text strings that may not contain unescaped curly brace or single quote characters. To include these special characters into string bodies, the characters must be escaped: curly braces must be enclosed within single quote characters ("'{'"), while real single quote characters are represented with two consequtive single quote characters ("''").

Format elements

elementKey refers to tuple element identity, as defined by TupleData.get(Object,Map) method. The elementKey is used to select the tuple member or an value from the current M_additionalValues} map whose value is to replace the whole corresponding format element. If the key does not match any tuple member or additional value, the format element will be replaced with an empty string.

It is perfectly legal to refer to the same element multiple times, or not to refer to an element at all. Elemens referred to multiple times will be copied into the resulting strings as many times, while elements not referenced at all will be omitted alltogether.

Element type

typeName and typeSpecs pattern components may be used to override the default tuple member value formatting instructions. In particular, the type name and spesification, if given, define together a new data type as described by Type.create(String,String,String,String) method. This type, if any, is then applied to the corresponding tuple member or additional value to convert it to a string. If no custom type is created, either due missing or invalid type name or spesification, the tuple member or additional value default string representation is used.

It is perfectly legal to apply different formats and even new data types to the tuple elements and additional values. Each different reference will format the value according to the given format spesification. If new types are applied to tuple members and values, the result of the type conversion will be used. If type conversion fails, the original default formatting will be used instead.

Since:

JDK1.1

See Also:

createType(java.lang.String), format(Object,StringBuffer,FieldPosition), setAdditionalValues(java.util.Map), TupleData, TupleData.get(Object,Map), TupleType, Type.create(String,String,String,String), Serialized Form

Nested Class Summary

Nested classes inherited from class java.text.Format

java.text.Format.Field

Field Summary

protected static int	ENC Element index for field encoding component.
static java.lang.String	ENCODING_NONE Do no encode macro expansions.
static java.lang.String	ENCODING_URL URLEncode macro expansions.
static java.lang.String	ENCODING_XML XML encode macro expansions.
protected static int	KEY Element index for field key component.
protected java.util.Map	M_additionalValues Additional values map.
protected java.util.List	M_fields Format fields.
protected java.util.Locale	M_locale Format locale.
protected java.lang.String	M_tail Format trailing constant string.
protected static int	STRING Element index for field string component.
protected static int	TYPE Element index for field type component.

Constructor Summary

TupleFormat(java.lang.String pattern, java.util.Locale locale, java.util.Map additionalValues)
Creates a new tuple formatter.

Method Summary

protected Type	createType(java.lang.String elementFormat) Creates a type from element format string.
java.lang.StringBuffer	format(java.lang.Object object, java.lang.StringBuffer toAppendTo, java.text.FieldPosition pos) Formats a TupleData object to produce a string.
java.util.Map	getAdditionalValues() Gets additional values map.
java.lang.String	getEncoding(int index) Gets the encoding of given field.
java.lang.String	getKey(int index) Gets the key of given field.
java.lang.String	getString(int index) Gets the string of given field.
Type	getType(int index) Gets the type of given field.
protected com.davisor.core.IndexLabel	indexOfStart(java.lang.String pattern, int start) Finds the next unescaped macro key start character from given pattern, and unescapes the string up to the found character.
protected int	indexOfStop(java.lang.String pattern, int start) Finds the next matching macro key stop characted index from given pattern.
java.lang.Object	parseObject(java.lang.String source, java.text.ParsePosition status) Parses a string to produce an object (not implemented).
void	setAdditionalValues(java.util.Map additionalValues) Sets additional values map.
int	size() Gets the number of fields.

Methods inherited from class java.text.Format

clone, format, formatToCharacterIterator, parseObject

Methods inherited from class java.lang.Object

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

Field Detail

STRING

protected static final int STRING

Element index for field string component.

See Also:

Constant Field Values

KEY

protected static final int KEY

Element index for field key component.

See Also:

Constant Field Values

TYPE

protected static final int TYPE

Element index for field type component.

See Also:

Constant Field Values

ENC

protected static final int ENC

Element index for field encoding component.

See Also:

Constant Field Values

ENCODING_NONE

public static final java.lang.String ENCODING_NONE

Do no encode macro expansions.

See Also:

Constant Field Values

ENCODING_URL

public static final java.lang.String ENCODING_URL

URLEncode macro expansions.

See Also:

Constant Field Values

ENCODING_XML

public static final java.lang.String ENCODING_XML

XML encode macro expansions.

See Also:

Constant Field Values

M_fields

protected java.util.List M_fields

Format fields.

M_locale

protected java.util.Locale M_locale

Format locale.

M_tail

protected java.lang.String M_tail

Format trailing constant string.

M_additionalValues

protected java.util.Map M_additionalValues

Additional values map.

Constructor Detail

TupleFormat

public TupleFormat(java.lang.String pattern,
                   java.util.Locale locale,
                   java.util.Map additionalValues)

Creates a new tuple formatter.

Parameters:

pattern - format spesification string

locale - locale for locale sensitive formatting

additionalValues - additional values for tuple member value resolvation (may be null)

See Also:

createType(java.lang.String), format(Object,StringBuffer,FieldPosition), indexOfStart(java.lang.String, int), indexOfStop(java.lang.String, int), setAdditionalValues(java.util.Map), TupleData, TupleData.get(Object,Map), TupleType

Method Detail

format

public java.lang.StringBuffer format(java.lang.Object object,
                                     java.lang.StringBuffer toAppendTo,
                                     java.text.FieldPosition pos)

Formats a TupleData object to produce a string. The string is composed from the content of given tuple object and current tuple format pattern.

For each format field in the current pattern, the tuple formatter makes a search to the given tuple data object, and substitutes found value, if any, with corresponding field key. Values not found show as empty strings.

The searches are carried out with tuple data TupleData.get(Object,Map) method, using the formatElements in the current format pattern as keys, and current additional values as additional value map.

Parameters:

object - the tuple data object to format

toAppendTo - where the text is to be appended

pos - ignored (may be null) @return the value passed in as toAppendTo

Throws:

java.lang.IllegalArgumentException - if object is not a tuple data object

See Also:

setAdditionalValues(java.util.Map), TupleData.get(Object,Map)

parseObject

public java.lang.Object parseObject(java.lang.String source,
                                    java.text.ParsePosition status)

Parses a string to produce an object (not implemented).

Returns:

always null

createType

protected Type createType(java.lang.String elementFormat)
                   throws NoSuchTypeException

Creates a type from element format string. Element format string is of the form:

typeName { "," specs }

typeName and specs fields refer to Type.create(String,String,String) method arguments with the same names.

Parameters:

elementFormat - element format spesification

Returns:

new type, based on given spesifications

Throws:

NoSuchTypeException - if type spesification was invalid

See Also:

Type.create(String,String,String,String)

indexOfStart

protected com.davisor.core.IndexLabel indexOfStart(java.lang.String pattern,
                                                   int start)

Finds the next unescaped macro key start character from given pattern, and unescapes the string up to the found character. The unescaped string will have all but consequtive single quote character pairs removed. The string ends just before the first open curly brace character not inside single quotes, or at the end of the pattern string, whichever comes first.

The result is packed into an index label that carries the StringBuffer object the unescaped string was collected into. The index of the found start character in given pattern string is stored in index label index.

Parameters:

pattern - pattern to search

start - index to start the search from

Returns:

unescaped string, and the start character index, if found, or -1, if not

indexOfStop

protected int indexOfStop(java.lang.String pattern,
                          int start)

Finds the next matching macro key stop characted index from given pattern. This method is not confused by macro begin and end character pairs placed inside each other.

Parameters:

pattern - pattern to search

start - index to start the search from

Returns:

stop character index, or -1 if no stop character was found

getAdditionalValues

public java.util.Map getAdditionalValues()

Gets additional values map.

See Also:

format(java.lang.Object, java.lang.StringBuffer, java.text.FieldPosition), setAdditionalValues(java.util.Map), TupleData.get(Object,Map), TupleType.getAdditionalValues()

getEncoding

public java.lang.String getEncoding(int index)

Gets the encoding of given field.

Parameters:

index - field index

Returns:

field encoding (may be null)

getKey

public java.lang.String getKey(int index)

Gets the key of given field.

Parameters:

index - field index

Returns:

field key (may be null)

getString

public java.lang.String getString(int index)

Gets the string of given field.

Parameters:

index - field index

Returns:

field string (may be null)

getType

public Type getType(int index)

Gets the type of given field.

Parameters:

index - field index.

Returns:

field type (may be null)

setAdditionalValues

public void setAdditionalValues(java.util.Map additionalValues)

Sets additional values map.

See Also:

format(java.lang.Object, java.lang.StringBuffer, java.text.FieldPosition), getAdditionalValues(), TupleData.get(Object,Map), TupleType.setAdditionalValues(java.util.Map)

size

public int size()

Gets the number of fields.