net.sourceforge.esw.collection
Class DelimitedTransducer

java.lang.Object
  |
  +--net.sourceforge.esw.collection.ATransducer
        |
        +--net.sourceforge.esw.collection.AIOTransducer
              |
              +--net.sourceforge.esw.collection.DelimitedTransducer

All Implemented Interfaces:

IIOTransducer, ITransducer, java.io.Serializable

public class DelimitedTransducer

extends AIOTransducer

Performs delimited transduction against a stream of data; fields, rows, records, and other data dimensions that are indicated by embedded Stringinstance or char actors.

This transduction occurs both ways; put() takes data from the IMetaCollection instance to which this ITransducer instance is attached and places it into the data source represented by this ITransducer instance. The get() method takes data from the data source represented by this ITransducer instance and places it into the IMetaCollection instance to which this ITransducer instance is attached.

This IIOTransducer implementor provides stream-based access for stream based ITransducer implementors. It abstracts out the setting and getting of the streams, or the Reader and Writer instances, into this interface.

A DelimitedTransducer instance is quite flexible. It can transduce data in any number of dimensions - e.g., a one-dimensional vector, a 2-dimensional table, or an n-dimensional array. The size of the rows in any given dimension can be uniform or varied, allowing, for example, uniform, irregular, sparse, even triangular matrices. Delimiters can be simple characters - for example, the familiar "tab-separated fields" method in which the tab character delimits fields and the newline character delimits rows. Delimiters are actually String instances for maximal flexibility. Delimiters can be set via the constructor or the addDelimiter or setDelimiter methods.

Delimiters are specified in dimensional order, numbered from 0. For a three dimensional matrix, for example, the 0th delimiter would separate the columns, the 1st would separate the rows, and the 2nd delimiter would separate pages (for lack of a better term). Data varies in dimensional order: all the columns within a row, all the columns in the next row, and so on through the last row of the page, then all the columns within the first row of the next page, all the columns within the next row, etc.

Delimiters may not be null.

Example:

    IMetaCollection meta = MetaFactory.createMetaCollection();
    DelimitedTransducer transducer = new DelimitedTransducer();
    transducer.setReader( getMyReader() ); // for files or strings or others...
    transducer.addDelimiter( "," );  // commas delimit the first dimension
    transducer.addDelimiter( "\n" ); // newlines delimit the second dimension
    meta.setTransducer( transducer );
    try {
      meta.get();
    }
    catch ( TransducerException te ) {
      te.printStackTrace(); // in case something went wrong.
    }
 

See Also:

Serialized Form

Field Summary

protected boolean	bWriteTrailingDelim If put transductions with this DelimitedTransducer should write out the trailing top level delimiter.
protected java.util.HashMap	delimiters The Map of delimiters for this ITransducer implementor, all of them with an Integer key and a String value.
protected int	size The size of the collection of delimiters, equal to the largest postion plus one.

Fields inherited from class net.sourceforge.esw.collection.AIOTransducer

reader, writer

Fields inherited from class net.sourceforge.esw.collection.ATransducer

contextFactory

Constructor Summary

DelimitedTransducer()
Creates a new DelimitedTransducer instance with no delimiters.

DelimitedTransducer(java.util.List aDelimiters)
Creates a new DelimitedTransducer instance with the specified List of delimiters.

DelimitedTransducer(java.lang.String[] aDelimiters)
Creates a new DelimitedTransducer instance with the specified array of delimiters.

Method Summary

void	addDelimiter(java.lang.String aDelimiter) Adds the specified delimiter to this DelimitedTransducer instance at the next availiable position.
void	get(IMetaCollection aCollection) Gets the data source's data represented by this ITransducer instance into the referenced IMetaCollection instance.
java.lang.String	getDelimiter(int aPosition) Returns the delimiter at the specified position.
int	getDelimiterPosition(java.lang.String aDelimiter) Returns the position for the specified delimiter within this DelimitedTransducer instance's List of delimiters.
protected java.util.ArrayList	getNextToken(java.io.Reader myReader) Returns the next token from the specified Reader instance.
boolean	getWriteTrailingDelimiter() Returns whether this DelimitedTransducer instance will write the trailing top level delimiter during put operations.
boolean	isTopDelimiter(java.lang.String aDelimiter) Returns whether the specified delimiter is the last delimiter added to this DelimitedTransducer instance.
void	put(IMetaCollection aCollection) Puts the referenced IMetaCollection instance's data into the data source represented by this ITransducer instance.
void	setDelimiter(int aPosition, java.lang.String aDelimiter) Sets a delimiter at the specified position for this DelimitedTransducer instance.
protected INode	setupBasicNodeStructure() Returns the graph from the INodeContextFactory instance.
void	setWriteTrailingDelimiter(boolean bWriteTrailingDelimiter) Sets whether this DelimitedTransducer instance will write the trailing top level delimiter during put method invocations.

Methods inherited from class net.sourceforge.esw.collection.AIOTransducer

getReader, getWriter, setReader, setWriter

Methods inherited from class net.sourceforge.esw.collection.ATransducer

getContextFactory, setContextFactory

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sourceforge.esw.collection.ITransducer

getContextFactory, setContextFactory

Field Detail

delimiters

protected java.util.HashMap delimiters

The Map of delimiters for this ITransducer implementor, all of them with an Integer key and a String value.

size

protected int size

The size of the collection of delimiters, equal to the largest postion plus one.

bWriteTrailingDelim

protected boolean bWriteTrailingDelim

If put transductions with this DelimitedTransducer should write out the trailing top level delimiter. Default is true.

Constructor Detail

DelimitedTransducer

public DelimitedTransducer()

Creates a new DelimitedTransducer instance with no delimiters.

DelimitedTransducer

public DelimitedTransducer(java.lang.String[] aDelimiters)

Creates a new DelimitedTransducer instance with the specified array of delimiters.

Parameters:

aDelimiters - the array of delimiters to add to this DelimitedTransducer instance.

DelimitedTransducer

public DelimitedTransducer(java.util.List aDelimiters)

Creates a new DelimitedTransducer instance with the specified List of delimiters.

Parameters:

aDelimiters - the List of delimiters to add to this DelimitedTransducer instance.

Method Detail

setWriteTrailingDelimiter

public void setWriteTrailingDelimiter(boolean bWriteTrailingDelimiter)

Sets whether this DelimitedTransducer instance will write the trailing top level delimiter during put method invocations. Default is true.

Parameters:

bWriteTrailingDelimiter - if this delimiter should write the trailing delimiter

See Also:

getWriteTrailingDelimiter()

getWriteTrailingDelimiter

public boolean getWriteTrailingDelimiter()

Returns whether this DelimitedTransducer instance will write the trailing top level delimiter during put operations. Default is true.

See Also:

setWriteTrailingDelimiter( boolean )

setDelimiter

public void setDelimiter(int aPosition,
                         java.lang.String aDelimiter)

Sets a delimiter at the specified position for this DelimitedTransducer instance.

Parameters:

aPosition - the delimiter's index position; index is 0 based.

aDelimiter - a new delimiter for this DelimitedTransducer instance to use.

Throws:

java.lang.IndexOutOfBoundsException - if the number of delimiters is less than the requested position for the new delimiter.

See Also:

addDelimiter( String ), getDelimiter( int ), getDelimiterPosition( String )

addDelimiter

public void addDelimiter(java.lang.String aDelimiter)

Adds the specified delimiter to this DelimitedTransducer instance at the next availiable position.

Parameters:

aDelimiter - a new delimiter for this DelimitedTransducer instance to use.

See Also:

setDelimiter( int, String ), getDelimiter( int ), getDelimiterPosition( String )

getDelimiter

public java.lang.String getDelimiter(int aPosition)

Returns the delimiter at the specified position. The positions are 0 based.

Parameters:

aPosition - the position of the delimiter to return.

Returns:

the delimiter at this position or null if no delimiter exists for that position.

See Also:

setDelimiter( int, String ), addDelimiter( String ), getDelimiterPosition( String )

getDelimiterPosition

public int getDelimiterPosition(java.lang.String aDelimiter)

Returns the position for the specified delimiter within this DelimitedTransducer instance's List of delimiters.

Parameters:

aDelimiter - the delimiter for which to find the position.

Returns:

the position of this delimiter, or -1 if this delimiter was not found.

See Also:

setDelimiter( int, String ), addDelimiter( String ), getDelimiter( int )

isTopDelimiter

public boolean isTopDelimiter(java.lang.String aDelimiter)

Returns whether the specified delimiter is the last delimiter added to this DelimitedTransducer instance.

Parameters:

aDelimiter - the delimiter to check.

Returns:

true if the specified delimiter is the top, otherwise false.

get

public void get(IMetaCollection aCollection)
         throws TransducerException

Gets the data source's data represented by this ITransducer instance into the referenced IMetaCollection instance.

Data for any given dimension can be uniform or irregular. If no data is present for a given dimension then the transducer inserts a null dimension into the collection to represent it. Higher-numbered delimiters will terminate lower-numbered dimensions: for instance, if delimiter n is encountered after parsing data of dimension n-2, then dimensions n-2,n-1, and n are all terminated.

Parameters:

aCollection - the IMetaCollection instance into which to read.

Throws:

TransducerException - if an error occurs during transduction.

See Also:

put( IMetaCollection )

put

public void put(IMetaCollection aCollection)
         throws TransducerException

Puts the referenced IMetaCollection instance's data into the data source represented by this ITransducer instance.

The output data format is well-formed: there are no missing delimiters.

Parameters:

aCollection - the IMetaCollection instance from which to take data.

Throws:

TransducerException - if an error occurs during transduction.

See Also:

get( IMetaCollection )

getNextToken

protected java.util.ArrayList getNextToken(java.io.Reader myReader)
                                    throws java.text.ParseException,
                                           java.io.IOException

Returns the next token from the specified Reader instance.

Parameters:

myReader - The Reader instance to use to get the next token.

Returns:

ArrayList A list that contains the token, and the delimiter.

setupBasicNodeStructure

protected INode setupBasicNodeStructure()

Returns the graph from the INodeContextFactory instance. If the graph doesn't contain enough depth to support the current number of delimiters, builds the structure up until the depth of the graph is equal to the number of delimiters.

Returns:

INode The graph structure.

See Also:

INodeContextFactory