de.infinityloop.upcast.exportfilters
Class ExportFilterBase

java.lang.Object
  extended by de.infinityloop.upcast.exportfilters.ExportFilter
      extended by de.infinityloop.upcast.exportfilters.RichExportFilter
          extended by de.infinityloop.upcast.exportfilters.ExportFilterBase
All Implemented Interfaces:
de.infinityloop.upcast.ModuleGUI

public abstract class ExportFilterBase
extends de.infinityloop.upcast.exportfilters.RichExportFilter


Field Summary
protected  int gprefIndentationFactor
          specified indentation step size.
protected  java.lang.String gprefNamespacePrefix
          The namespace prefix to use when outputting with namespace.
protected  boolean gprefPrettyPrint
          a boolean indicating whether pretty printing is to be performed.
protected  java.lang.String gprefStyleAttrName
          Name for the local CSS styling attribute.
protected  boolean gprefUseNamespace
          Determines whether output of upCast elements should be done with the upCast namespace (=true) or in the null namespace (=false).
static java.lang.String kDiffStyleAttrName
          attribute local name of the private diffStyle attribute
protected static int kFilterRequiredFrameVersion
          the required minimal version of upCast for this filter to run.
protected static int kFilterVersion
          The version of the filter implementation.
static java.lang.String kFullStyleAttrName
          attribute local name of the private fullStyle attribute
protected static java.lang.String kGraphicalAttrName
          name of the attribute holding the css local override style information for the respective element.
static java.lang.String kInfinityloopInternalNamespace
          Namespace of infinity-loop application-internal (private) attributes.
protected static java.lang.String kLogicalAttrName
          name of the attribute holding the css class name of the respective lement.
protected  de.infinityloop.upcast.importfilters.RTFImportFilter rtfInFilter
           
 
Fields inherited from class de.infinityloop.upcast.exportfilters.RichExportFilter
elementNameConversionTable, indentationLevel, inFilter, inOriginalText, kContentDTD, kEndTag, kIndentationStep, kMinimizedEndTag, kNoEndTag, kVisualDTD
 
Fields inherited from class de.infinityloop.upcast.exportfilters.ExportFilter
converterParent, cssDefaultUnits, instanceID, kAllowEmptyCellsParamName, kCALSTableModelParamValue, kCombineWithLogicalStyleParamName, kCommandlineFilterName, kCommandlineParamName, kConfigurationFileParamName, kCPU_UpcastDefaultMap, kCSSFilterName, kCSSPropertyUnitMapParamName, kCSSRefParamName, kCSSSelectorSyntaxParamName, kCustomStylesheetJarPathParamName, kCustomStylesheetPIParamName, kDecryptionKey, kDeleteAfterConversionParamName, kDeleteEmptiesParamName, kDocBookFilterName, kDocBookRootParamName, kDOCTYPEDeclarationParamName, kDTDTypeDTDParamValue, kDTDTypeParamName, kDTDTypeXMLSchemaParamValue, kFilterNameParamName, kHTMLTableModelParamValue, kIncludeHiddenContentsParamName, kIncludeVisualElementsParamName, kInfileParamName, kInlineCSSStylesheetParamName, kMacronameParamName, kNamespacePrefixParamName, kOutfileParamName, kOutputEncodingParamName, kOutputResolutionParamName, kPrecompileStylesheetParamName, kQualityFactorParamName, kRawTreeParamName, kRepeatInlineClassPropertiesOnElement, kRevisionTrackingParamName, kRTFImport, kStandalone, kStylesheetParametersParamName, kStylesheetParamName, kSuffixParamName, kSuffixParamName_OLD, kTableModelParamName, kUnicodeTranslationMapParamName, kUnicodeTranslatorFilterName, kUpcastDefaultCSSUnitMapPath, kUpcastDefaultMapPath, kUpcastHTMLMapPath, kUpcastNSXMLMapPath, kUpcastXMLMapPath, kUseNamespaceParamName, kUTM_UpcastDefaultMap, kUTM_UpcastHTMLMap, kUTM_UpcastXMLMap, kValidateParamName, kValidatorFilterName, kWaitForCompletionParamName, kWriteDTDParamName, kWriteTOCParamName, kXHTMLFilterName, kXHTMLTransitionalFilterName, kXMLBasicDTDXSLTFilterName, kXMLFilterName, kXMLVersionParamName, kXSLTProcessorFilterName, kXSLTProcessorParamName, logger, serverMode
 
Constructor Summary
ExportFilterBase()
          The constructor.
ExportFilterBase(boolean sMode, de.infinityloop.upcast.Converter c)
          The constructor.
 
Method Summary
 java.lang.String canAdd(de.infinityloop.upcast.Converter c)
          Checks if this filter can be added to the list of currently active export filters.
protected abstract  void characters(java.lang.String text)
          Called by the framework for document character content.
protected  java.util.Vector convertPropertyListToVector(java.lang.String plist)
          breaks a complete CSS property string into Pair()s of property name, property value.
protected  int convertTwipsToPixels(int twips)
          converts the passed value in twips to pixels, based on output resolution set in the upCast Import filter dialog.
protected  void customConfigurationEditorDismissed(boolean ok)
          Called by the framework when the configuration editor was dismissed by the user by either clicking "OK" or "Cancel".
 void doExport(de.infinityloop.upcast.Converter parent, OutputProxy op)
          This method exports the whole document in the format as implemented by the export filter class.
protected  java.lang.String encodeForClassAttribute(java.lang.String s)
          Helper: Encodes the passed class name for commpatibility with the CSS export filter.
protected  java.lang.String encodeForXMLAttribute(java.lang.String s)
          Helper: Encodes the passed String for use as an XML 1.0 attribute value string.
protected  java.lang.String encodeForXMLText(java.lang.String s)
          Helper: Encodes the passed String for use as character data in XML 1.0.
protected abstract  void endDocument()
          Called by the framework after finishing the conversion.
protected abstract  void endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes attr)
          Called by the framework at the end of an element.
protected  java.lang.String extractPropertyValue(org.xml.sax.Attributes atts, java.lang.String propName, java.lang.String unit)
          Extracts a single value from a CSS property string's property with the name propName.
protected  java.lang.String formatAttribute(org.xml.sax.Attributes atts, java.lang.String attName)
          Helper: Formats an attribute value for writing as XML.
protected  java.lang.String formatAttribute(org.xml.sax.Attributes atts, java.lang.String attName, java.lang.String destName)
          Helper: Formats an attribute value for writing as XML, using the specified different attribute name for the result.
protected  java.lang.String formatAttributeFiltered(org.xml.sax.Attributes atts, java.lang.String attName, CSSPropertyFilter propfilter)
          Helper: Formats an attribute value for writing as XML, filtering on Attributes containing CSS using the specified filter.
protected  java.lang.String formatAttributeNMTOKEN(org.xml.sax.Attributes atts, java.lang.String attName)
          Helper: Formats an attribute value for writing as XML and makes sure that it is a NMTOKEN compliant value.
protected  java.lang.String getApplicationVersionAsString()
          retrieves the upCast application's version as String.
 java.lang.String getConfigAsText()
          This is called by the framework when it needs a String of text representing the current filter settings in human-readable form.
protected  java.util.Stack getCustomConfigurationEditorTabs()
          This function must return a Stack object containing (String tabTitle, JComponent tabContent) Pair()s for use in one tab each of the standard interface provided by the upCast framework.
protected  java.lang.String getDiffStyleFiltered(org.xml.sax.Attributes atts, CSSPropertyFilter f)
          Helper: Extracts the differential style attribute from the passed Attributes object, and optionally filters it against a passed PropertyFilter.
 int getFilterCompatibility()
          retrieves filter compatibility constant
 int getFilterVersion()
          Returns filter version number kFilterVersion.
protected  java.lang.String getFullStyleFiltered(org.xml.sax.Attributes atts, CSSPropertyFilter f)
          Helper: Extracts the base/full style attribute from the passed Attributes object, and optionally filters it against a passed PropertyFilter.
protected abstract  java.lang.String getHumanReadableConfigurationDescription()
          This is called by the framework when it needs a String of text representing the current filter settings in human-readable form.
abstract  java.lang.String getIdentificationName()
          Returns the "internal" name of this filter, i.e. the one by which this filter is selected in BCF or upCast API.
protected  java.lang.String getMangledComponent(java.lang.String s, int componentIndex)
          Retrieves the component with a specified index of a mangled string.
 java.lang.String getModuleClassName()
          Returns the module class name, which will be shown in the list of available export filters popup menu.
 java.lang.String getModuleName()
          Returns the filter instance name set by the user.
protected  boolean getParameterBoolean(java.lang.String param, boolean dflt)
          Retrieves the named preferences object belonging to this filter from the preferences pool as a boolean value.
protected  double getParameterDouble(java.lang.String param, double dflt)
          Retrieves the named preferences object belonging to this filter from the preferences pool as a double value.
protected  int getParameterInt(java.lang.String param, int dflt)
          Retrieves the named preferences object belonging to this filter from the preferences pool as an integer value.
protected  java.lang.String getParameterString(java.lang.String param, java.lang.String dflt)
          Retrieves the named preferences object belonging to this filter from the preferences pool as a String.
 int getRequiredJRE()
          Returns the minimum Java/JDK version required to run the filter.
 boolean hasConfigDialog()
          Indicates to the framework whether this filter implementation has a configuration dialog at all.
protected  void indent()
          Increases current indentation level by 1.
protected  java.lang.String indentation()
          Calculates the currently valid indentation string, based on the current indentation level (as implicitly set by using indent() and outdent() methods).
protected  java.lang.String indentation(int steps, java.lang.String indentationElement)
          Calculates the indentation string based on the passed values.
 void initializeConfig()
          Initializes filter parameters to their default values.
protected  void initializeConfiguration()
          Initializes custom filter parameters to their default values.
 int initializeFilter(int frameVersion)
          Initialize Filter.
 void issueDebug(long flags, java.lang.String debugMessage)
          Records a debugging message in the log.
 void issueError(int code, java.lang.Object[] params)
           
 void issueError(java.lang.String errorMessage)
          Reports an error to the user.
 void issueInfo(java.lang.String infoMessage)
          Records an informative message in the log.
 void issueWarning(int code, java.lang.Object[] params)
           
 void issueWarning(java.lang.String warningMessage)
          Reports a warning to the user.
protected abstract  void literal(java.lang.String literalData)
          Called by the framework for literal destination document content.
protected  java.lang.String makeFinalTag(java.lang.String tag)
          Generates the final tag name from the tag given as parameter.
protected  void nl(java.io.Writer w)
          writes the platform-dependent newline character.
protected  void outdent()
          Decreases current indentation level by 1.
 boolean presentConfigDialog(javax.swing.JFrame parent)
          Create and present the configuration dialog.
 void removeConfig()
          Removes any parameters stored in the preferences for this filter instance.
 void reset()
          Initialize global instance variables before a run.
protected  java.lang.String resolveExpression(java.lang.String expression)
          Resolves a string containing variables referencing current runtime file information.
protected  boolean runsWithUI()
          Returns true when upCast is running in GUI mode, false otherwise.
 void setParameter(java.lang.String name, java.lang.Object value)
          Put a new named value into this filter's preferences parameter pool.
protected  void setProgressMessage(java.lang.String message)
          Set the label of the progress bar to the specified text to inform the user of the action currently taking place.
protected abstract  void startDocument(java.io.Writer destination, java.lang.String systemId)
          Called by the framework when starting a new document conversion.
protected abstract  void startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes attr)
          Called by the framework at the start of an element.
protected  java.lang.String translateClassAttrForCSS(java.lang.String s)
          Helper: Translates class names from their Word representation to a CSS-compatible version, without making them XML writable; this has to be done in a second step by calling encodeForXMLAttribute().
 void updateConfig()
          By calling this method, the framework indicates that preference values might have changed out of control of the filter and therefore any cached values need to be re-read from the preferences pool.
protected  void updateConfiguration()
          By calling this method, the framework indicates that preference values might have changed out of control of the filter and therefore any cached values need to be re-read from the preferences pool.
protected  void userCancelled()
          This method is called by the framework when it has detected that the user clicked the "Cancel" button in the progress display UI element.
protected  void writeNode(java.io.Writer out, org.w3c.dom.Node node, int writeEndTag)
          This handles recursively calling the SAX like API methods for custom eport filters.
protected  void writeXMLProlog(java.io.Writer w)
          writes the XML prolog, including the current encoding attribute.
 
Methods inherited from class de.infinityloop.upcast.exportfilters.RichExportFilter
calculateCSSStylesheet, calculateDTDElementsCSSDefaults, calculatePagesizeCSS, filterPropertyString, getDefaultParKind, getHTMLColor, getLogger, hasAncestorElement, hasVisualContent, indentLevel, makeCLASSAttr_XML, makePCDATA_XML, makePCDATAAttr_XML, makeXMLName, outdentLevel, writeAllChildren, writeCopyrightHeaderXML, writeElement, writeElement, writeIndentation, writeIndentationEndTag, writeInfoGroupAsXML
 
Methods inherited from class de.infinityloop.upcast.exportfilters.ExportFilter
findPreferences, getConverterParent, getDoc, getFilter, getInstanceSelector, getPreferenceAsBoolean, getPreferenceAsDouble, getPreferenceAsInt, getPreferenceAsLong, getPreferenceAsString, getServerMode, getTextFromSubtree, removeParameter, setConverterParent, setInstanceSelector, setServerMode
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface de.infinityloop.upcast.ModuleGUI
getInstanceSelector, setInstanceSelector
 

Field Detail

kFilterVersion

protected static int kFilterVersion
The version of the filter implementation. This is in the Macintosh 'vers' format: 0xMMmr with MM=major version, m=minor version, r=revision. Override this in your implementation.


kFilterRequiredFrameVersion

protected static int kFilterRequiredFrameVersion
the required minimal version of upCast for this filter to run. Default: 0x0400 (=4.0.0)


kInfinityloopInternalNamespace

public static final java.lang.String kInfinityloopInternalNamespace
Namespace of infinity-loop application-internal (private) attributes.

See Also:
Constant Field Values

kFullStyleAttrName

public static final java.lang.String kFullStyleAttrName
attribute local name of the private fullStyle attribute

See Also:
Constant Field Values

kDiffStyleAttrName

public static final java.lang.String kDiffStyleAttrName
attribute local name of the private diffStyle attribute

See Also:
Constant Field Values

kLogicalAttrName

protected static final java.lang.String kLogicalAttrName
name of the attribute holding the css class name of the respective lement.

See Also:
Constant Field Values

kGraphicalAttrName

protected static final java.lang.String kGraphicalAttrName
name of the attribute holding the css local override style information for the respective element.

See Also:
Constant Field Values

rtfInFilter

protected de.infinityloop.upcast.importfilters.RTFImportFilter rtfInFilter

gprefPrettyPrint

protected boolean gprefPrettyPrint
a boolean indicating whether pretty printing is to be performed. Can be overridden by subclasses.


gprefIndentationFactor

protected int gprefIndentationFactor
specified indentation step size. Default: indent 2 spaces per level. Can be overridden by subclasses.


gprefNamespacePrefix

protected java.lang.String gprefNamespacePrefix
The namespace prefix to use when outputting with namespace. Override as desired, default is "uc".


gprefUseNamespace

protected boolean gprefUseNamespace
Determines whether output of upCast elements should be done with the upCast namespace (=true) or in the null namespace (=false). Set as desired.


gprefStyleAttrName

protected java.lang.String gprefStyleAttrName
Name for the local CSS styling attribute. This holds the diffStyle CSS string.

Constructor Detail

ExportFilterBase

public ExportFilterBase(boolean sMode,
                        de.infinityloop.upcast.Converter c)
The constructor. Filter implementations may never call this directly!


ExportFilterBase

public ExportFilterBase()
The constructor. Filter implementations may never call this directly!

Method Detail

getFilterCompatibility

public int getFilterCompatibility()
retrieves filter compatibility constant

Specified by:
getFilterCompatibility in class de.infinityloop.upcast.exportfilters.ExportFilter

initializeFilter

public int initializeFilter(int frameVersion)
Initialize Filter. This is called by the framework immediately after instantiating this filter, for example at launch time when creating the the GUI popup of available filters. Override this if your capability to run depends on the current environment, which you can check here.

Specified by:
initializeFilter in class de.infinityloop.upcast.exportfilters.ExportFilter
Parameters:
frameVersion - the framework version; use this to check against your required framework version.
Returns:
the filter version in 'vers' format, if you can run, or -1 if requirements check failed.

getFilterVersion

public int getFilterVersion()
Returns filter version number kFilterVersion. You normally need not override this.

Specified by:
getFilterVersion in class de.infinityloop.upcast.exportfilters.ExportFilter

canAdd

public java.lang.String canAdd(de.infinityloop.upcast.Converter c)
Checks if this filter can be added to the list of currently active export filters.

Overrides:
canAdd in class de.infinityloop.upcast.exportfilters.ExportFilter
Parameters:
c - the parent converter object (opaque)
Returns:
null, if this filter may be added by the user to the current list of active export filters, or an error String indicating why this is not possible, which is presented to the user.

reset

public void reset()
Initialize global instance variables before a run. This is called by the framework before starting an export filter run. You may use it for example to reset instance variables.

Overrides:
reset in class de.infinityloop.upcast.exportfilters.RichExportFilter

doExport

public final void doExport(de.infinityloop.upcast.Converter parent,
                           OutputProxy op)
                    throws java.lang.Exception
This method exports the whole document in the format as implemented by the export filter class. This is final, you cannot override this.

Specified by:
doExport in class de.infinityloop.upcast.exportfilters.ExportFilter
Throws:
java.lang.Exception

writeNode

protected final void writeNode(java.io.Writer out,
                               org.w3c.dom.Node node,
                               int writeEndTag)
                        throws java.lang.Exception
This handles recursively calling the SAX like API methods for custom eport filters. You cannot override this method.

Overrides:
writeNode in class de.infinityloop.upcast.exportfilters.RichExportFilter
Throws:
java.lang.Exception

makeFinalTag

protected final java.lang.String makeFinalTag(java.lang.String tag)
Generates the final tag name from the tag given as parameter. Used to prepend the "uc:" namespace name. You cannot override this.

Overrides:
makeFinalTag in class de.infinityloop.upcast.exportfilters.RichExportFilter

writeXMLProlog

protected void writeXMLProlog(java.io.Writer w)
                       throws java.io.IOException
writes the XML prolog, including the current encoding attribute. If any global document comment was collected, this is written here, as well.

Parameters:
w - The current Writer object used for output
Throws:
java.io.IOException

indentation

protected java.lang.String indentation(int steps,
                                       java.lang.String indentationElement)
Calculates the indentation string based on the passed values.

Parameters:
steps - number of steps to indent using the indentationElement
indentationElement - the string that indents one level, e.g. " " (a space)
Returns:
the string that constitutes the desired indentation when printed at the start of the line

indentation

protected java.lang.String indentation()
Calculates the currently valid indentation string, based on the current indentation level (as implicitly set by using indent() and outdent() methods).

Returns:
the full indentation string as it should be printed from the beginning of the line

indent

protected void indent()
Increases current indentation level by 1.


outdent

protected void outdent()
Decreases current indentation level by 1.


nl

protected void nl(java.io.Writer w)
           throws java.io.IOException
writes the platform-dependent newline character.

Parameters:
w - the current Writer object used for output
Throws:
java.io.IOException

setProgressMessage

protected final void setProgressMessage(java.lang.String message)
Set the label of the progress bar to the specified text to inform the user of the action currently taking place.

Parameters:
message - the action message text

getApplicationVersionAsString

protected final java.lang.String getApplicationVersionAsString()
retrieves the upCast application's version as String.


getMangledComponent

protected final java.lang.String getMangledComponent(java.lang.String s,
                                                     int componentIndex)
Retrieves the component with a specified index of a mangled string. To learn which attributes' values are mangled, see the accompanying documentation.

Parameters:
s - The mangled string
componentIndex - the index of the component you want to retrieve. Components are numbered starting at 0.
Returns:
The component or null, if no component with that index exists.

convertTwipsToPixels

protected int convertTwipsToPixels(int twips)
converts the passed value in twips to pixels, based on output resolution set in the upCast Import filter dialog.

Parameters:
twips - the value in twips you want to know the pixel equivalent of
Returns:
the value in pixels equivalent to the passed value in twips

resolveExpression

protected final java.lang.String resolveExpression(java.lang.String expression)
Resolves a string containing variables referencing current runtime file information. Supported placeholders:

Parameters:
expression - - the String expression to resolve
Returns:
the resolved string

convertPropertyListToVector

protected java.util.Vector convertPropertyListToVector(java.lang.String plist)
breaks a complete CSS property string into Pair()s of property name, property value.

Parameters:
plist - the property list String to be broken up into propertyname/value Pair()s
Returns:
a Vector of propertyname/value Pair()s.
See Also:
Pair

extractPropertyValue

protected java.lang.String extractPropertyValue(org.xml.sax.Attributes atts,
                                                java.lang.String propName,
                                                java.lang.String unit)
Extracts a single value from a CSS property string's property with the name propName. You can also specify the unit the result should be returned in (incl. the resp. unit identifier). This will only take effect for properties having a unit as opposed to text content or keywords.

Parameters:
atts - the Attributes object passed. This contains two attributes holding style information, the base style and some overriding style properties. This method merges these two styles and then performs the search automatically.
propName - name of the property to extract, e.g. 'width' or 'list-style-type'.
unit - the unit name of the value should be converted to (only for properties of type length), e.g. "in" or "px"
Returns:
the value of the requested property or null, if it was not found

presentConfigDialog

public boolean presentConfigDialog(javax.swing.JFrame parent)
Create and present the configuration dialog. You only need to override this if you need to present a fully customized configuration dialog and do not want to just implement the simplified hook functions getCustomConfigurationEditorTabs() and customConfigurationEditorDismissed(). This method is called by the framework whenever the user clicks the "Configure..." button in the UI.

Specified by:
presentConfigDialog in interface de.infinityloop.upcast.ModuleGUI
Overrides:
presentConfigDialog in class de.infinityloop.upcast.exportfilters.ExportFilter
Parameters:
parent - the JFrame parent any presented dialog should use as its parent
Returns:
true if dialog handling was successful; false when there was some error during dialog creation, display or handling.

getConfigAsText

public java.lang.String getConfigAsText()
This is called by the framework when it needs a String of text representing the current filter settings in human-readable form. It is used for display in the upCast main window. You probably do not want to override this when implementing getHumanReadableConfigurationDescription().

Specified by:
getConfigAsText in interface de.infinityloop.upcast.ModuleGUI
Overrides:
getConfigAsText in class de.infinityloop.upcast.exportfilters.ExportFilter
Returns:
a String representing the current filter state.

initializeConfig

public final void initializeConfig()
Initializes filter parameters to their default values. Cannot be overridden, but calls initializeConfiguration().

Specified by:
initializeConfig in interface de.infinityloop.upcast.ModuleGUI
Overrides:
initializeConfig in class de.infinityloop.upcast.exportfilters.ExportFilter
See Also:
initializeConfiguration()

removeConfig

public final void removeConfig()
Removes any parameters stored in the preferences for this filter instance. Cannot be overridden.


updateConfig

public final void updateConfig()
By calling this method, the framework indicates that preference values might have changed out of control of the filter and therefore any cached values need to be re-read from the preferences pool. This might be the case when the user chooses to load a different settings document. Cannot be overridden, but calls updateConfiguration().

Specified by:
updateConfig in interface de.infinityloop.upcast.ModuleGUI
Overrides:
updateConfig in class de.infinityloop.upcast.exportfilters.ExportFilter
See Also:
updateConfiguration()

getModuleName

public final java.lang.String getModuleName()
Returns the filter instance name set by the user. Cannot be overridden.

Specified by:
getModuleName in interface de.infinityloop.upcast.ModuleGUI
Overrides:
getModuleName in class de.infinityloop.upcast.exportfilters.ExportFilter
Returns:
the name given by the user to this filter instance

hasConfigDialog

public boolean hasConfigDialog()
Indicates to the framework whether this filter implementation has a configuration dialog at all. Return false if you do not provide a for filter settings, which will make the framework disable the "Configure..." button in the main UI.

Specified by:
hasConfigDialog in interface de.infinityloop.upcast.ModuleGUI
Overrides:
hasConfigDialog in class de.infinityloop.upcast.exportfilters.ExportFilter
Returns:
true if a configuration UI is provided, false otherwise.

getModuleClassName

public java.lang.String getModuleClassName()
Returns the module class name, which will be shown in the list of available export filters popup menu. You should override this method and deliver a meaningful, short filter class name.

Specified by:
getModuleClassName in interface de.infinityloop.upcast.ModuleGUI
Overrides:
getModuleClassName in class de.infinityloop.upcast.exportfilters.ExportFilter
Returns:
descriptive short filter class name

getIdentificationName

public abstract java.lang.String getIdentificationName()
Returns the "internal" name of this filter, i.e. the one by which this filter is selected in BCF or upCast API. Don't confuse with getModuleClassName(), which is the name displayed in the GUI. This method MUST be overridden in real filter implementations. Must return the name of this filter (-class), as is also used in
  1. the preferences file
  2. the batch importer XML
The name should follow the rules for a NMTOKEN, i.e. it should not contain whitespace characters.

Specified by:
getIdentificationName in interface de.infinityloop.upcast.ModuleGUI
Specified by:
getIdentificationName in class de.infinityloop.upcast.exportfilters.ExportFilter

getRequiredJRE

public int getRequiredJRE()
Returns the minimum Java/JDK version required to run the filter. Format: 110 for 1.1.0, 120 for 1.2.0 etc. The default is 120, so you need only override this when you require a later version of the JDK to run.

Specified by:
getRequiredJRE in interface de.infinityloop.upcast.ModuleGUI
Overrides:
getRequiredJRE in class de.infinityloop.upcast.exportfilters.ExportFilter
Returns:
an integer indicating the minimum JRE version this filter requires.

formatAttribute

protected java.lang.String formatAttribute(org.xml.sax.Attributes atts,
                                           java.lang.String attName)
Helper: Formats an attribute value for writing as XML. Prepends a space if the value can be generated, otherwise it returns an empty string, so you can concatenate results without worrying about separating whitespace.

Parameters:
atts - the Attributes object where attName might be a member of
attName - the name of the attribute that should be formatted
Returns:
a String of the form: ' ' attName '="' attValue '"'

formatAttribute

protected java.lang.String formatAttribute(org.xml.sax.Attributes atts,
                                           java.lang.String attName,
                                           java.lang.String destName)
Helper: Formats an attribute value for writing as XML, using the specified different attribute name for the result. Prepends a space if the value can be generated, otherwise it returns an empty string, so you can concatenate results without worrying about separating whitespace.

Parameters:
atts - the Attributes object where attName might be a member of
attName - the name of the attribute that should be formatted
destName - the name for the attribute to use in the result string
Returns:
a String of the form: ' ' attName '="' attValue '"'

formatAttributeFiltered

protected java.lang.String formatAttributeFiltered(org.xml.sax.Attributes atts,
                                                   java.lang.String attName,
                                                   CSSPropertyFilter propfilter)
Helper: Formats an attribute value for writing as XML, filtering on Attributes containing CSS using the specified filter. Prepends a space if the value can be generated, otherwise it returns an empty string, so you can concatenate results without worrying about separating whitespace.

Parameters:
atts - the Attributes object where attName might be a member of
attName - the name of the attribute that should be formatted
propfilter - the property filter description object
Returns:
a String of the form: ' ' attName '="' attValue '"'

formatAttributeNMTOKEN

protected java.lang.String formatAttributeNMTOKEN(org.xml.sax.Attributes atts,
                                                  java.lang.String attName)
Helper: Formats an attribute value for writing as XML and makes sure that it is a NMTOKEN compliant value. The algorithm of the NMTOKEN conformance enforcement is the same for identical input. Prepends a space if the value can be generated, otherwise it returns an empty string, so you can concatenate results without worrying about separating whitespace.

Parameters:
atts - the Attributes object where attName might be a member of
attName - the name of the attribute that should be formatted
Returns:
a String of the form: ' ' attName '="' attValue '"'

getDiffStyleFiltered

protected java.lang.String getDiffStyleFiltered(org.xml.sax.Attributes atts,
                                                CSSPropertyFilter f)
Helper: Extracts the differential style attribute from the passed Attributes object, and optionally filters it against a passed PropertyFilter.

Parameters:
atts - the Attributes object
f - the property filter to filter against
Returns:
the differential style as CSS string or the empty string, if not found.

getFullStyleFiltered

protected java.lang.String getFullStyleFiltered(org.xml.sax.Attributes atts,
                                                CSSPropertyFilter f)
Helper: Extracts the base/full style attribute from the passed Attributes object, and optionally filters it against a passed PropertyFilter.

Parameters:
atts - the Attributes object
f - the property filter to filter against
Returns:
the differential style as CSS string or the empty string, if not found.

encodeForXMLAttribute

protected final java.lang.String encodeForXMLAttribute(java.lang.String s)
Helper: Encodes the passed String for use as an XML 1.0 attribute value string.

Parameters:
s - Unicode attribute value String to encode
Returns:
the encoded string for direct use as value string in an XML 1.0 attribute

encodeForXMLText

protected final java.lang.String encodeForXMLText(java.lang.String s)
Helper: Encodes the passed String for use as character data in XML 1.0.

Parameters:
s - Unicode character string to be encoded
Returns:
the encoded string for direct use as character data in XML 1.0.

encodeForClassAttribute

protected final java.lang.String encodeForClassAttribute(java.lang.String s)
Helper: Encodes the passed class name for commpatibility with the CSS export filter.

Parameters:
s - CSS class name
Returns:
the encoded string for use as value string in the class="..." attribute.

translateClassAttrForCSS

protected final java.lang.String translateClassAttrForCSS(java.lang.String s)
Helper: Translates class names from their Word representation to a CSS-compatible version, without making them XML writable; this has to be done in a second step by calling encodeForXMLAttribute().

Parameters:
s - CSS class name
Returns:
the encoded string for use as value e.g. in the cssclass attribute.

runsWithUI

protected final boolean runsWithUI()
Returns true when upCast is running in GUI mode, false otherwise.

Returns:
true when UI is available, false otherwise.

getParameterBoolean

protected final boolean getParameterBoolean(java.lang.String param,
                                            boolean dflt)
Retrieves the named preferences object belonging to this filter from the preferences pool as a boolean value.

Parameters:
param - the name (key) of the parameter to retrieve
dflt - the default value to use when the requested parameter is not found in the preferences pool
Returns:
the value of the retrieved parameter (or the specified default value if it has not been found)

getParameterInt

protected final int getParameterInt(java.lang.String param,
                                    int dflt)
Retrieves the named preferences object belonging to this filter from the preferences pool as an integer value.

Parameters:
param - the name (key) of the parameter to retrieve
dflt - the default value to use when the requested parameter is not found in the preferences pool
Returns:
the value of the retrieved parameter (or the specified default value if it has not been found)

getParameterDouble

protected final double getParameterDouble(java.lang.String param,
                                          double dflt)
Retrieves the named preferences object belonging to this filter from the preferences pool as a double value.

Parameters:
param - the name (key) of the parameter to retrieve
dflt - the default value to use when the requested parameter is not found in the preferences pool
Returns:
the value of the retrieved parameter (or the specified default value if it has not been found)

getParameterString

protected final java.lang.String getParameterString(java.lang.String param,
                                                    java.lang.String dflt)
Retrieves the named preferences object belonging to this filter from the preferences pool as a String.

Parameters:
param - the name (key) of the parameter to retrieve
dflt - the default value to use when the requested parameter is not found in the preferences pool
Returns:
the value of the retrieved parameter (or the specified default value if it has not been found)

setParameter

public void setParameter(java.lang.String name,
                         java.lang.Object value)
Put a new named value into this filter's preferences parameter pool.

Overrides:
setParameter in class de.infinityloop.upcast.exportfilters.ExportFilter
Parameters:
name - the name of the parameter; may not contain the dot '.' character as that is used internally to separate namespace hierarchies.
value - the value object. This can be one of the following standard classes: String, Integer, Double, Boolean. Storage of arbitrary objects is not supported in this version!

issueError

public void issueError(java.lang.String errorMessage)
Reports an error to the user. Also marks the current conversion as being "not successful", triggering display of an error dialog to the user and/or throwing an exception in API mode.

Parameters:
errorMessage - the error message string to display

issueError

public void issueError(int code,
                       java.lang.Object[] params)

issueWarning

public void issueWarning(java.lang.String warningMessage)
Reports a warning to the user. Does not mark this conversion as unsuccessful.

Parameters:
warningMessage - the warning message to write to the log file

issueWarning

public void issueWarning(int code,
                         java.lang.Object[] params)

issueInfo

public void issueInfo(java.lang.String infoMessage)
Records an informative message in the log.

Parameters:
infoMessage - the informative message to write to the log file

issueDebug

public void issueDebug(long flags,
                       java.lang.String debugMessage)
Records a debugging message in the log. The message will only be recorded if the logging level is set to debug, either by the user having set the "de.infinityloop.debug=true" property on application startup, by using a modified log4j.properties file in the jar or by having set it programmatically using the corresponding upCast API methods.

Parameters:
debugMessage - the debug message to write to the log file

getCustomConfigurationEditorTabs

protected java.util.Stack getCustomConfigurationEditorTabs()
This function must return a Stack object containing (String tabTitle, JComponent tabContent) Pair()s for use in one tab each of the standard interface provided by the upCast framework.

Returns:
a Stack of (String tabTitle, JComponent tabContent) Pair()s to serve as content of a tab in the JTabbedPanel-based UI of the framework, or null if you do not want to add a customized UI extension.

customConfigurationEditorDismissed

protected void customConfigurationEditorDismissed(boolean ok)
Called by the framework when the configuration editor was dismissed by the user by either clicking "OK" or "Cancel". Which of the two is indicated by the passed parameter. Use this to retrieve the current values from your custom UI you provided in getCustomConfigurationEditorTabs() and put them into the preferences pool using setParameter() when the user has clicked "OK". You probably will not do anything in this methods when the ok parameter is false.

Parameters:
ok - true when the user clicked "OK" to dismiss the dialog, false otherwise.

getHumanReadableConfigurationDescription

protected abstract java.lang.String getHumanReadableConfigurationDescription()
This is called by the framework when it needs a String of text representing the current filter settings in human-readable form. It is used for display in the upCast main window.

Returns:
a String representing the current filter state, starting with ", " (comma and space character). This is appended to the default description string generated by the framework automatically.

userCancelled

protected void userCancelled()
This method is called by the framework when it has detected that the user clicked the "Cancel" button in the progress display UI element. Do whatever you want here, probably closing additionally opened files out of control of the framework etc.


initializeConfiguration

protected void initializeConfiguration()
Initializes custom filter parameters to their default values. This is called by the framework after creating a new instance of this filter. You should set default values for all parameters your filter uses in the preferences pool in this method.


updateConfiguration

protected void updateConfiguration()
By calling this method, the framework indicates that preference values might have changed out of control of the filter and therefore any cached values need to be re-read from the preferences pool. This might be the case when the user chooses to load a different settings document. Called by the default implementation of updateConfig() before it re-reads its own cached parameters, so you might use this place to check bounds on certain parameters or reset them to fixed values the user may not change.

See Also:
updateConfig()

startDocument

protected abstract void startDocument(java.io.Writer destination,
                                      java.lang.String systemId)
Called by the framework when starting a new document conversion.

Parameters:
destination - the Writer you should write the result to
systemId - the URL/file name of the destination file; might not be valid when the conversion's originally destination was already a Stream with no associated location information.

endDocument

protected abstract void endDocument()
                             throws java.lang.Exception
Called by the framework after finishing the conversion.

Throws:
java.lang.Exception

startElement

protected abstract void startElement(java.lang.String uri,
                                     java.lang.String localName,
                                     java.lang.String qName,
                                     org.xml.sax.Attributes attr)
Called by the framework at the start of an element. Has the same semanics as the corresponding SAX2 interface method.


endElement

protected abstract void endElement(java.lang.String uri,
                                   java.lang.String localName,
                                   java.lang.String qName,
                                   org.xml.sax.Attributes attr)
Called by the framework at the end of an element. Has the same semantics as the corresponding SAX2 interface method. IMPORTANT CHANGE:This method takes now an additional parameter, namely the same Attributes object that was passed in already for the startElement() call. This is often handy to perform a different end element action based on the element's attributes, and you need not keep a stack of Attributes yourself. Updating old code is easy, simply add the parameter to your method implementation - you need not use it for anything.

Since:
4.0.2b25

characters

protected abstract void characters(java.lang.String text)
Called by the framework for document character content. Has the same semantics as the corresponding SAX2 interface method.


literal

protected abstract void literal(java.lang.String literalData)
Called by the framework for literal destination document content. You may not perform XML quoting or any transformations on the passed data, but must write it 1:1 to the destination Writer.