com.ibm.spatial.io
Class GeometryWriter

java.lang.Object
  com.ibm.spatial.io.GeometryWriter

public abstract class GeometryWriter
extends java.lang.Object

An abstract superclass for encoding and writing of geometry objects. This class must be subclassed by classes that write geometries. GeometryWriter objects can normally write data in a specific format.

See Also:

GeometryReader, SpatialManager

Method Summary

void	abort() Requests that any current write operation be aborted.
boolean	canInsert(int index) Determines whether a writer supports insertion of a new geometry at the given position.
void	dispose() Allows any resources held by this object to be released.
java.lang.String	getFormatName() Returns a String identifying the format of the input source.
java.lang.Object	getOutput() Returns the OutputStream or other Object previously set as the output.
void	reset() Restores the GeometryWriter to its initial state.
void	setOutput(java.lang.Object output) Sets the output to the specified OutputStream or other Object.
void	write(Geometry geometry) Appends a geometry to the output.
abstract void	write(Geometry geometry, java.lang.Object[] args) Appends a geometry to the output.
void	write(int index, Geometry geometry, java.lang.Object[] args) Inserts a new geometry into an existing stream at a position specified by index.

Methods inherited from class java.lang.Object

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

Method Detail

reset

public void reset()

Restores the GeometryWriter to its initial state. This implementation calls setOutput(null).

dispose

public void dispose()

Allows any resources held by this object to be released. The default implementation does nothing.

getFormatName

public java.lang.String getFormatName()
                               throws java.io.IOException

Returns a String identifying the format of the input source.

This implementation returns the empty string.

Returns:

a String object identifying the format of the input source.

Throws:

java.io.IOException

write

public abstract void write(Geometry geometry,
                           java.lang.Object[] args)
                    throws java.io.IOException,
                           SpatialException

Appends a geometry to the output. If the output is an OutputStream, its existing contents prior to the current seek position are not affected.

The output must have been set beforehand using the setOutput method.

A set of arguments may optionally be specified in args to control the writing.

Writers extending this class may handle special cases (foe example writing a file header) by setting geometry to null and setting the header data in args in a format documented locally.

Parameters:

a - geometry object to be written to the current output

args - optional arguments to be passed to the write process

Throws:

java.io.IOException - if an error occurs during writing

SpatialException - if a spatial data format error occurs during writing

write

public void write(Geometry geometry)
           throws java.io.IOException,
                  SpatialException

Appends a geometry to the output. If the output is an OutputStream, its existing contents prior to the current seek position are not affected.

The output must have been set beforehand using the setOutput method.

This implementation calls write(geometry, null).

Parameters:

a - geometry object to be written to the current output

Throws:

java.io.IOException - if an error occurs during writing

SpatialException - if a spatial data format error occurs during writing

canInsert

public boolean canInsert(int index)
                  throws java.io.IOException

Determines whether a writer supports insertion of a new geometry at the given position. In case of an insertion, existing geometries with indices greater than or equal to the insertion position will be shifted with one position towards greater indices. If index is -1 then the insertion position is after the last geometry in the output sequence.

If a writer does not support insertions, it may return false on any index.

The default implementation throws an IllegalStateException if the output is null, otherwise it returns false.

Parameters:

index - the position (0-based) at which the geometry is to be inserted

Returns:

true if a geometry may be inserted at the given position

Throws:

java.lang.IllegalStateException - if the output has not been set

java.lang.IndexOutOfBoundsException - if the writer supports insertion in general, but index < -1 or greater than the largest available index

java.io.IOException - if an I/O error occurs

write

public void write(int index,
                  Geometry geometry,
                  java.lang.Object[] args)
           throws java.io.IOException,
                  SpatialException

Inserts a new geometry into an existing stream at a position specified by index. Existing geometries with indices greater than or equal to the insertion position will be shifted with one position towards greater indices. If index is -1 then the insertion position is after the last geometry in the output sequence. If the output is an OutputStream, the whole stream must be both readable and writeable.

If canInsert(index) returns false, an UnsupportedOperationException will be thrown.

Write arguments may optionally be supplied in args. If no write arguments are needed, then args is ignored.

Writers extending this class may handle special cases (foe example writing a file header) by setting geometry to null and setting the header data in args in a format documented locally.

The default implementation throws an IllegalStateException if the output is null, and otherwise throws an UnsupportedOperationException.

Parameters:

index - the position (0-based) at which the geometry is to be inserted

geometry - a Geometry object to be written

args - an array of arguments to control the write operation

Throws:

java.lang.IllegalStateException - if the output has not been set

java.lang.UnsupportedOperationException - if canInsert(index) returns false.

java.lang.IllegalArgumentException - if geometry is null.

java.lang.IndexOutOfBoundsException - if index is less than -1 or greater than the largest available index.

java.io.IOException - if an error occurs during writing

SpatialException - if a spatial data format error occurs during writing

setOutput

public void setOutput(java.lang.Object output)

Sets the output to the specified OutputStream or other Object. The output must be set before any write methods are used. Any currently set output will be removed if output is null.

Parameters:

output - the OutputStream or other Object to use as a data sink

Throws:

java.lang.IllegalArgumentException - if output is not an acceptable instance

See Also:

getOutput()

getOutput

public java.lang.Object getOutput()

Returns the OutputStream or other Object previously set as the output. If the output has not been set, null is returned.

Returns:

the Object that will be used for future encoding and writing, or null.

See Also:

setOutput(java.lang.Object)

abort

public void abort()

Requests that any current write operation be aborted.

Writers should call clearAbortFlag at the beginning of each write, and poll the value of abortFlag during the write.