io.starter.OpenXLS

Class DocumentHandle

java.lang.Object

io.starter.OpenXLS.DocumentHandle

All Implemented Interfaces:

Document, Handle, Closeable, AutoCloseable

Direct Known Subclasses:

WorkBookHandle

public abstract class DocumentHandle
extends Object
implements Document, Handle, Closeable

Functionality common to all document types.

Field Summary

Fields

Modifier and Type	Field and Description
protected int	DEBUGLEVEL The level of debugging output requested by the user.
protected File	file The file associated with this document.
static int	FORMAT_NATIVE Format constant for the most appropriate format for this document.
protected String	name The user-visible display name or title of this document.
static String	workingdir

Fields inherited from interface io.starter.OpenXLS.Document

DEBUG_HIGH, DEBUG_LOW, DEBUG_MEDIUM

Constructor Summary

Constructors

Constructor and Description
DocumentHandle() default constructor
DocumentHandle(File input)
DocumentHandle(InputStream urlx) Apr 5, 2011

Method Summary

Modifier and Type	Method and Description
void	addProperty(String name, Object val) Sets the value of a property in the workbook property store.
int	getDebugLevel()
File	getFile() Gets the file associated with this document.
abstract String	getFileExtension() Gets the file name extension for this document's native format.
protected static File	getFileFromURL(URL u) Deprecated. The download should be handled outside OpenXLS. There is no specific replacement for this method.
String	getFileName() Deprecated. Use getFile() instead.
abstract int	getFormat() Gets the constant representing this document's native format.
static DocumentHandle	getInstance(InputStream input) Looks for magic numbers in the given input data and attempts to parse it with an appropriate DocumentHandle subclass.
String	getName() Gets the user-visible descriptive name or title of this document.
Map<String,Object>	getProperties() Retrieves a Map containing the workbook properties store.
Object	getProperty(String name) Retrieves a property in the workbook property store.
static String	getVersion() Gets the OpenXLS version number.
abstract void	reset() Resets the document state to what it was when it was loaded.
void	setDebugLevel(int level) Sets the debugging output level.
void	setFile(File file) Sets the file associated with this document.
void	setFileName(String name) Deprecated. Use setFile(File) instead.
void	setName(String nm) Sets the user-visible descriptive name or title of this document.
void	setProperties(Map<String,Object> properties) Replaces the workbook properties with the values in a given Map.
void	setStreamingSheets(boolean streamSheets) Handling for streaming sheets.
String	toString() Returns a string representation of the object.
void	write(File file) Writes the document to the given file in its native format.
void	write(File file, int format) Writes the document to the given file in the requested format.
void	write(OutputStream dest) Writes the document to the given stream in its native format.
abstract void	write(OutputStream dest, int format) Writes the document to the given stream in the requested format.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.io.Closeable

close

Field Detail

workingdir

public static String workingdir

FORMAT_NATIVE

public static final int FORMAT_NATIVE

Format constant for the most appropriate format for this document. If the document was read in from a file, this is usually the format that was read in.

See Also:

Constant Field Values

DEBUGLEVEL

protected int DEBUGLEVEL

The level of debugging output requested by the user. Higher values should produce more output.

name

protected String name

The user-visible display name or title of this document.

file

protected File file

The file associated with this document. This will generally be the file the document was parsed from, if any.

Constructor Detail

DocumentHandle

public DocumentHandle()

default constructor

DocumentHandle

public DocumentHandle(InputStream urlx)

Apr 5, 2011

Parameters:

urlx -

DocumentHandle

public DocumentHandle(File input)

Method Detail

getProperty

public Object getProperty(String name)

Retrieves a property in the workbook property store. This is not an Excel-compatible feature.

Specified by:

getProperty in interface Document

Parameters:

name - the name of the property to retrieve

Returns:

the value of the requested property or null if it doesn't exist

addProperty

public void addProperty(String name,
                        Object val)

Sets the value of a property in the workbook property store. This is not an Excel-compatible feature.

Specified by:

addProperty in interface Document

Parameters:

name - the name of the property which should be updated

value - the value to which the property should be set

getProperties

public Map<String,Object> getProperties()

Retrieves a Map containing the workbook properties store. This is not an Excel-compatible feature.

Returns:

an immutable Map containing the current workbook properties

setProperties

public void setProperties(Map<String,Object> properties)

Replaces the workbook properties with the values in a given Map. This is not an Excel-compatible feature.

Parameters:

properties - the values that will replace the existing properties

getVersion

public static String getVersion()

Gets the OpenXLS version number.

setName

public void setName(String nm)

Sets the user-visible descriptive name or title of this document. Some formats will persist this setting in the document itself.

Specified by:

setName in interface Document

setStreamingSheets

public void setStreamingSheets(boolean streamSheets)

Handling for streaming sheets. Currently this is in development and unsupported

Parameters:

streamSheets -

setFileName

@Deprecated
public void setFileName(String name)

Deprecated. Use setFile(File) instead.

Sets the file name associated with this document.

setFile

public void setFile(File file)

Sets the file associated with this document.

getFile

public File getFile()

Gets the file associated with this document. For documents read in from a file, this defaults to that file. If no file is associated with this document, for example if the document was parsed from a stream, this may return null.

getInstance

public static DocumentHandle getInstance(InputStream input)
                                  throws IOException

Looks for magic numbers in the given input data and attempts to parse it with an appropriate DocumentHandle subclass. Detection is performed on a best-effort basis and is not guaranteed to be accurate.

Throws:

IOException - if an error occurs while reading from the stream

WorkBookException - if parsing fails

getFileName

@Deprecated
public String getFileName()

Deprecated. Use getFile() instead.

Gets the file name associated with this document. For documents read in from a file, this defaults to that file. If no file is associated with this document, for example if the document was parsed from a stream, this may return null.

setDebugLevel

public void setDebugLevel(int level)

Sets the debugging output level. Higher values will produce more output. Output at higher values will generally only be of use to OpenXLS developers. Increased output incurs a performance penalty, so it is recommended this be left at zero unless you are reporting a bug.

Specified by:

setDebugLevel in interface Document

getDebugLevel

public int getDebugLevel()

getFileFromURL

@Deprecated
protected static File getFileFromURL(URL u)

Deprecated. The download should be handled outside OpenXLS. There is no specific replacement for this method.

Downloads the resource at the given URL to a temporary file.

Parameters:

u - the URL representing the resource to be downloaded

Returns:

the path to a temporary file containing the downloaded resource or null if an error occurred

getName

public String getName()

Gets the user-visible descriptive name or title of this document.

Specified by:

getName in interface Document

Returns:

String name of WorkBook

reset

public abstract void reset()

Resets the document state to what it was when it was loaded.

Specified by:

reset in interface Document

Throws:

UnsupportedOperationException - if there is not sufficient data available to perform the reversion

getFormat

public abstract int getFormat()

Gets the constant representing this document's native format.

getFileExtension

public abstract String getFileExtension()

Gets the file name extension for this document's native format.

write

public abstract void write(OutputStream dest,
                           int format)
                    throws IOException

Writes the document to the given stream in the requested format.

Specified by:

write in interface Document

Parameters:

dest - the stream to which the document should be written

format - the constant representing the desired output format

Throws:

IllegalArgumentException - if the given type code is invalid

IOException - if an error occurs while writing to the stream

write

public void write(OutputStream dest)
           throws IOException

Writes the document to the given stream in its native format.

Specified by:

write in interface Document

Parameters:

dest - the stream to which the document should be written

Throws:

IOException - if an error occurs while writing to the stream

write

public void write(File file,
                  int format)
           throws IOException

Writes the document to the given file in the requested format.

Specified by:

write in interface Document

Parameters:

file - the path to which the document should be written

format - the constant representing the desired output format

Throws:

IllegalArgumentException - if the given type code is invalid

IOException - if an error occurs while writing to the file

write

public void write(File file)
           throws IOException

Writes the document to the given file in its native format.

Specified by:

write in interface Document

Parameters:

file - the path to which the document should be written

Throws:

IOException - if an error occurs while writing to the stream

toString

public String toString()

Returns a string representation of the object. This is currently equivalent to getName().

Overrides:

toString in class Object