net.bitform.api.options

Class OptionSet

java.lang.Object

net.bitform.api.options.OptionSet

Direct Known Subclasses:

BasicRequest

public class OptionSet
extends java.lang.Object

A type-safe collection of option/value pairs. This class acts as the basis for setting, getting, saving and loading parameters to all Clean Content APIs. More specifically is acts as a base class for the SecureRequest class.

Method Summary

Modifier and Type	Method and Description
void	addTo(OptionSet target) Add all options to a target option set.
void	clearAllOptions() Clears all options from the option set.
void	clearOption(Option option) Clears a given option from the option set.
boolean	compare(OptionSet set) Type specific version of the equals method
void	copyTo(OptionSet target) Copy all options to a target option set.
void	copyTo(OptionSet target, Option option) Copy a single option to a target option set.
OptionSet	createBasedOn() Creates a new option set with the same option values as this option set.
boolean	equals(java.lang.Object obj) Equals
AnalyzeOption.Action	getOption(AnalyzeOption target) Gets the action associated with one of the targets in SecureOptions
boolean	getOption(BooleanOption option) Gets a boolean option
java.util.Date	getOption(DateOption option) Gets a date option
java.io.File	getOption(DirectoryOption option) Gets a directory option
Duration	getOption(DurationOption option) Gets a duration option
EnumOptionValue[]	getOption(EnumListOption option) Gets a enum list option
EnumOptionValue	getOption(EnumOption option) Gets an enum option
FileFormat[]	getOption(FileFormatListOption option) Gets a file format list option
FileFormat	getOption(FileFormatOption option) Gets a file format option
FileOptionValue[]	getOption(FileListOption option) Gets a file list option
FileOptionValue	getOption(FileOption option) Gets a file option
double	getOption(FloatOption option) Gets an float option
ElementHandler	getOption(HandlerOption option) Gets a handler option
long	getOption(IntegerOption option) Gets an integer option
java.lang.Object[]	getOption(ObjectListOption option) Gets an object list option.
java.lang.Object	getOption(ObjectOption option) Gets an object option.
ScrubOption.Action	getOption(ScrubOption target) Gets the action associated with one of the scrub targets in SecureOptions
java.lang.String[]	getOption(StringListOption option) Gets a string list option
java.lang.String	getOption(StringOption option) Gets a string option
int	getOptionEnumAsInt(EnumOption option) Gets an enum option as integer This method is provided for efficency in the C/C++ API and should not be called directly.
int	getOptionFileFormatAsInt(FileFormatOption option) Gets a file format option as unique id This method is provided for efficency in the C/C++ API and should not be called directly.
int[]	getOptionFileFormatListAsIntArray(FileFormatListOption option) Gets a file format list option This method is provided for efficency in the C/C++ API and should not be called directly.
org.xml.sax.ContentHandler	getXMLHandler(org.xml.sax.XMLReader reader) Gets an implementation of a SAX ContentHandler that will read and verify the XML subtree written by the writeXML(ContentHandler ch) method.
boolean	isSet(Option option) Tests if a given option has been set
static OptionSet	newEmptyOptionSet() Creates an option set with no options set.
void	readXML(java.io.File file) Reads options from an option set file previously saved using writeXML
static void	registerOptions(OptionContainer options) Registers a set of options.
void	setOption(AnalyzeOption target, AnalyzeOption.Action action) Sets an action on one of the targets in SecureOptions
void	setOption(BooleanOption option, boolean value) Sets a boolean option
void	setOption(DateOption option, java.util.Date value) Sets a date option
void	setOption(DateOption option, int year, int month, int day, int hour, int minute, int second) Sets a date option
void	setOption(DirectoryOption option, java.io.File value) Sets a directory option
void	setOption(DurationOption option, Duration value) Sets a duration option
void	setOption(DurationOption option, int value) Sets a duration option
void	setOption(EnumListOption option, EnumOptionValue[] values) Sets a enum list option
void	setOption(EnumListOption option, int[] values) Sets a enum list option using unique ids This method is provided for efficency in the C/C++ API and should not be called directly.
void	setOption(EnumOption option, EnumOptionValue value) Sets an enum option
void	setOption(EnumOption option, int value) Sets an enum option using its unique id.
void	setOption(FileFormatListOption option, FileFormat[] value) Sets a file format list option
void	setOption(FileFormatListOption option, int[] values) Sets a file format list option using unique ids This method is provided for efficency in the C/C++ API and should not be called directly.
void	setOption(FileFormatOption option, FileFormat value) Sets a file format option
void	setOption(FileFormatOption option, int value) Sets a file format option using the format's unique id This method is provided for efficency in the C/C++ API and should not be called directly.
void	setOption(FileListOption option, java.io.File[] files) Sets a file list option
void	setOption(FileListOption option, FileOptionValue[] files) Sets a file list option
void	setOption(FileOption option, java.nio.ByteBuffer value) Sets a file option using a ByteBuffer
void	setOption(FileOption option, java.io.File value) Sets a file option using a File object
void	setOption(FileOption option, java.nio.channels.FileChannel value) Sets a file option using a FileChannel
void	setOption(FileOption option, java.io.InputStream value) Sets a file option using a InputStream
void	setOption(FileOption option, java.io.OutputStream value) Sets a file option using a OutputStream
void	setOption(FileOption option, SimpleChannel value) Sets a file option using a SimpleChannel
void	setOption(FileOption option, java.net.URL value) Sets a file option using a URL object
void	setOption(FloatOption option, double value) Sets an float option
void	setOption(HandlerOption option, ElementHandler handler) Sets a handler option.
void	setOption(IntegerOption option, long value) Sets an integer option
void	setOption(ObjectListOption option, java.lang.Object[] value) Sets an object list option.
void	setOption(ObjectOption option, java.lang.Object value) Sets an object option.
void	setOption(ScrubOption target, ScrubOption.Action action) Sets an action on one of the targets in SecureOptions
void	setOption(StringListOption option, java.lang.String[] value)
void	setOption(StringOption option, java.lang.String value) Sets a string option
void	writeXML(org.xml.sax.ContentHandler ch) Persists the option set as an XML subtree to an existsing SAX ContentHandler.
void	writeXML(org.xml.sax.ContentHandler ch, Option option) Persists a single option to an existsing SAX ContentHandler.
void	writeXML(java.io.File file) Persists the option set to a file.

Methods inherited from class java.lang.Object

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

Method Detail

equals

public boolean equals(java.lang.Object obj)

Equals

Overrides:

equals in class java.lang.Object

compare

public boolean compare(OptionSet set)

Type specific version of the equals method

Parameters:

set - option set to compare to this one

Returns:

true only if the sets contain exactly the same options with the same values

newEmptyOptionSet

public static OptionSet newEmptyOptionSet()

Creates an option set with no options set.

Returns:

A new, empty option set

isSet

public boolean isSet(Option option)

Tests if a given option has been set

Parameters:

option - The option to test

Returns:

true if the option has been set, false if the option has not been set

clearOption

public void clearOption(Option option)

Clears a given option from the option set. The option returns to its default value.

Parameters:

option - The option to clear

clearAllOptions

public void clearAllOptions()

Clears all options from the option set. All options return to their default values.

copyTo

public void copyTo(OptionSet target)

Copy all options to a target option set.

Parameters:

target - An option set that will receive a copy of the options. Any existing options in this target set will be removed.

addTo

public void addTo(OptionSet target)

Add all options to a target option set.

Parameters:

target - An option set that will receive a copy of the options. Any other existing options in this target will be preserved.

copyTo

public void copyTo(OptionSet target,
                   Option option)

Copy a single option to a target option set.

Parameters:

target - An option set that will receive a copy of the option.

option - The option to copy.

createBasedOn

public OptionSet createBasedOn()

Creates a new option set with the same option values as this option set. Options are not copied deeply so option types that have mutable object representations like StringListOption, FileFormatListOption and EnumListOption will receive the same object not a copy of the object.

Returns:

a new option set that contains the same values as this option set

setOption

public void setOption(EnumOption option,
                      EnumOptionValue value)

Sets an enum option

Parameters:

option - The EnumOption to set

value - The value this option should take

setOption

public void setOption(EnumOption option,
                      int value)

Sets an enum option using its unique id. This method is provided for efficency in the C/C++ API and should not be called directly.

Parameters:

option - The EnumOption to set

value - The value this option should take

getOption

public EnumOptionValue getOption(EnumOption option)

Gets an enum option

Parameters:

option - The EnumOption to get

Returns:

The value of this option

getOptionEnumAsInt

public int getOptionEnumAsInt(EnumOption option)

Gets an enum option as integer This method is provided for efficency in the C/C++ API and should not be called directly.

Parameters:

option - The EnumOption to get

Returns:

The value of this option

setOption

public void setOption(EnumListOption option,
                      EnumOptionValue[] values)

Sets a enum list option

Parameters:

option - The EnumListOption to set

values - The values this option should take

setOption

public void setOption(EnumListOption option,
                      int[] values)

Sets a enum list option using unique ids This method is provided for efficency in the C/C++ API and should not be called directly.

Parameters:

option - The EnumListOption to set

values - The values this option should take

getOption

public EnumOptionValue[] getOption(EnumListOption option)

Gets a enum list option

Parameters:

option - The EnumListOption to get

Returns:

The value of this option or NULL if the option is not set

setOption

public void setOption(BooleanOption option,
                      boolean value)

Sets a boolean option

Parameters:

option - The BooleanOption to set

value - The value this option should take

getOption

public boolean getOption(BooleanOption option)

Gets a boolean option

Parameters:

option - The BooleanOption to get

Returns:

The value of this option

setOption

public void setOption(StringOption option,
                      java.lang.String value)

Sets a string option

Parameters:

option - The StringOption to set

value - The value this option should take

getOption

public java.lang.String getOption(StringOption option)

Gets a string option

Parameters:

option - The StringOption to get

Returns:

The value of this option

setOption

public void setOption(DateOption option,
                      java.util.Date value)

Sets a date option

Parameters:

option - The DateOption to set

value - The value this option should take

setOption

public void setOption(DateOption option,
                      int year,
                      int month,
                      int day,
                      int hour,
                      int minute,
                      int second)

Sets a date option

Parameters:

option - The DateOption to set

year - The year, value is AD

month - The month, value is 0-based where 0 is January

day - Day of the month

hour - Hour

minute - Minute

second - Second

getOption

public java.util.Date getOption(DateOption option)

Gets a date option

Parameters:

option - The DateOption to get

Returns:

The value of this option

setOption

public void setOption(DurationOption option,
                      Duration value)

Sets a duration option

Parameters:

option - The DurationOption to set

value - The value this option should take

setOption

public void setOption(DurationOption option,
                      int value)

Sets a duration option

Parameters:

option - The DurationOption to set

value - The duration in milliseconds

getOption

public Duration getOption(DurationOption option)

Gets a duration option

Parameters:

option - The DurationOption to get

Returns:

The value of this option

setOption

public void setOption(StringListOption option,
                      java.lang.String[] value)

getOption

public java.lang.String[] getOption(StringListOption option)

Gets a string list option

Parameters:

option - The StringListOption to get

Returns:

The value of this option

setOption

public void setOption(IntegerOption option,
                      long value)

Sets an integer option

Parameters:

option - The IntegerOption to set

value - The value this option should take

getOption

public long getOption(IntegerOption option)

Gets an integer option

Parameters:

option - The IntegerOption to get

Returns:

The value of this option

setOption

public void setOption(FloatOption option,
                      double value)

Sets an float option

Parameters:

option - The FloatOption to set

value - The value this option should take

getOption

public double getOption(FloatOption option)

Gets an float option

Parameters:

option - The FloatOption to get

Returns:

The value of this option

setOption

public void setOption(ObjectOption option,
                      java.lang.Object value)

Sets an object option.

This method should be used to set options that take objects from other packages.

Parameters:

option - The Option to set

value - The value this option should take

getOption

public java.lang.Object getOption(ObjectOption option)

Gets an object option.

This method should be used only as an option extensibility mechanism and cannot be used to get any of Bitform's standard options.

Parameters:

option - The Option to set

Returns:

The value of this option

setOption

public void setOption(ObjectListOption option,
                      java.lang.Object[] value)

Sets an object list option.

This method should be used to set options that take object lists.

Parameters:

option - The Option to set

values - The list of values this option should take

getOption

public java.lang.Object[] getOption(ObjectListOption option)

Gets an object list option.

Parameters:

option - The Option to set

Returns:

The list of values for this option

setOption

public void setOption(FileFormatOption option,
                      FileFormat value)

Sets a file format option

Parameters:

option - The FileFormatOption to set

value - The value this option should take

setOption

public void setOption(FileFormatOption option,
                      int value)

Sets a file format option using the format's unique id This method is provided for efficency in the C/C++ API and should not be called directly.

Parameters:

option - The FileFormatOption to set

value - The value this option should take

getOption

public FileFormat getOption(FileFormatOption option)

Gets a file format option

Parameters:

option - The FileFormatOption to get

Returns:

The value of this option or NULL if the option is not set

getOptionFileFormatAsInt

public int getOptionFileFormatAsInt(FileFormatOption option)

Gets a file format option as unique id This method is provided for efficency in the C/C++ API and should not be called directly.

Parameters:

option - The FileFormatOption to get

Returns:

The value of this option or the id for FileFormat.UNKNOWN if not set

setOption

public void setOption(FileFormatListOption option,
                      FileFormat[] value)

Sets a file format list option

Parameters:

option - The FileFormatListOption to set

value - The value this option should take

setOption

public void setOption(FileFormatListOption option,
                      int[] values)

Sets a file format list option using unique ids This method is provided for efficency in the C/C++ API and should not be called directly.

Parameters:

option - The FileFormatListOption to set

values - The value this option should take

getOption

public FileFormat[] getOption(FileFormatListOption option)

Gets a file format list option

Parameters:

option - The FileFormatListOption to get

Returns:

The value of this option or NULL if the option is not set

getOptionFileFormatListAsIntArray

public int[] getOptionFileFormatListAsIntArray(FileFormatListOption option)

Gets a file format list option This method is provided for efficency in the C/C++ API and should not be called directly.

Parameters:

option - The FileFormatListOption to get

Returns:

The value of this option or NULL if the option is not set

setOption

public void setOption(DirectoryOption option,
                      java.io.File value)

Sets a directory option

Parameters:

option - The DirectoryOption to set

value - The value this option should take

getOption

public java.io.File getOption(DirectoryOption option)

Gets a directory option

Parameters:

option - The DirectoryOption to get

Returns:

The value of this option or NULL if the option is not set

setOption

public void setOption(FileListOption option,
                      FileOptionValue[] files)

Sets a file list option

Parameters:

option - The FileListOption to set

files - A non-null array of FileOptionValue objects

setOption

public void setOption(FileListOption option,
                      java.io.File[] files)

Sets a file list option

Parameters:

option - The FileListOption to set

files - A non-null array of File objects

getOption

public FileOptionValue[] getOption(FileListOption option)

Gets a file list option

Parameters:

option - The FileListOption to get

Returns:

An array of FileOptionValue objects or null if this option has not been set.

setOption

public void setOption(FileOption option,
                      java.io.File value)

Sets a file option using a File object

Parameters:

option - The FileOption to set

value - A non-null File object that represents a single file

setOption

public void setOption(FileOption option,
                      java.net.URL value)

Sets a file option using a URL object

Parameters:

option - TheFileOption to set

value - A non-null URL object that represents a single file

setOption

public void setOption(FileOption option,
                      java.io.InputStream value)

Sets a file option using a InputStream

Parameters:

option - The FileOption to set

value - A non-null InputStream object that represents a single file

setOption

public void setOption(FileOption option,
                      java.io.OutputStream value)

Sets a file option using a OutputStream

Parameters:

option - The FileOption to set

value - A non-null OutputStream object that represents a single file

setOption

public void setOption(FileOption option,
                      java.nio.channels.FileChannel value)

Sets a file option using a FileChannel

Parameters:

option - The FileOption to set

value - A non-null FileChannel object that represents a single file

setOption

public void setOption(FileOption option,
                      java.nio.ByteBuffer value)

Sets a file option using a ByteBuffer

Parameters:

option - The FileOption to set

value - A non-null ByteBuffer object that represents a single file

setOption

public void setOption(FileOption option,
                      SimpleChannel value)

Sets a file option using a SimpleChannel

Parameters:

option - The FileOption to set

value - A non-null SimpleChannel object that represents a single file

getOption

public FileOptionValue getOption(FileOption option)

Gets a file option

Parameters:

option - The FileOption to get

Returns:

A FileOptionValue object that represents a single file or NULL if this option has not been set.

setOption

public void setOption(ScrubOption target,
                      ScrubOption.Action action)

Sets an action on one of the targets in SecureOptions

Parameters:

target - One of the ScrubOption fields in SecureOptions

action - The action to perform on this target

getOption

public ScrubOption.Action getOption(ScrubOption target)

Gets the action associated with one of the scrub targets in SecureOptions

Parameters:

target - One of the fields in SecureOptions

Returns:

The action that will be performed

setOption

public void setOption(AnalyzeOption target,
                      AnalyzeOption.Action action)

Sets an action on one of the targets in SecureOptions

Parameters:

target - One of the AnalyzeOption fields in SecureOptions

action - The action to perform on this target

getOption

public AnalyzeOption.Action getOption(AnalyzeOption target)

Gets the action associated with one of the targets in SecureOptions

Parameters:

target - One of the fields in SecureOptions

Returns:

The action that was performed

setOption

public void setOption(HandlerOption option,
                      ElementHandler handler)

Sets a handler option.

Parameters:

option - A HandlerOption

handler - The element handler to associate with this option

getOption

public ElementHandler getOption(HandlerOption option)

Gets a handler option

Parameters:

option - A HandlerOption

Returns:

The handler associated with this option

registerOptions

public static void registerOptions(OptionContainer options)

Registers a set of options. Most developers can safely ignore this method since all Bitform APIs automatically register their options.

Parameters:

options - An option container that should be registered

writeXML

public void writeXML(java.io.File file)

Persists the option set to a file. The persisted form is an XML file using the namespace Bitform.OPTIONS_NAMESPACE.

The persisted file can be loaded back into an option set during construction of one of the concrete option sets, such as SecureRequest, that derive from this class.

Parameters:

file - File to persist to. File will be overwritten if it already exists.

writeXML

public void writeXML(org.xml.sax.ContentHandler ch)
              throws org.xml.sax.SAXException

Persists the option set as an XML subtree to an existsing SAX ContentHandler. The persisted form will use the namespace defined by Bitform.OPTIONS_NAMESPACE namespace.

The method allows an option set to be persisted as part of a larger XML file or saved in any other way that can expose a ContentHandler.

Parameters:

ch - SAX ContentHandler to write the XML subtree to.

Throws:

org.xml.sax.SAXException

writeXML

public void writeXML(org.xml.sax.ContentHandler ch,
                     Option option)
              throws org.xml.sax.SAXException

Persists a single option to an existsing SAX ContentHandler. The persisted form will use the namespace defined by Bitform.OPTIONS_NAMESPACE namespace.

The method allows a single option to be persisted as part of a larger XML file or saved in any other way that can expose a ContentHandler.

Parameters:

ch - SAX ContentHandler to write the XML subtree to.

option - The option to persist

Throws:

org.xml.sax.SAXException

readXML

public void readXML(java.io.File file)

Reads options from an option set file previously saved using writeXML

Parameters:

file - An XML file to read the options from. The file must exist.

getXMLHandler

public org.xml.sax.ContentHandler getXMLHandler(org.xml.sax.XMLReader reader)

Gets an implementation of a SAX ContentHandler that will read and verify the XML subtree written by the writeXML(ContentHandler ch) method.

It is the callers responsibility to send this ContentHandler only the SAX events for the subtree originally written by the writeXML(ContentHandler ch) method. Any other elements will throw a SAXException.

Returns:

A SAX ContentHandler ready to consume the subtree