com.deltaxml.odf.merge
Class OdtMerger

java.lang.Object
  com.deltaxml.odf.merge.OdtMerger

public class OdtMerger
extends Object

Merges two or more ODT (ISO/IEC 26300 v1.1) files and generates a result which contains changes relative to the first input (or base document) in the tracked-changes format.

NB: the ODT Merger only supports ODF packages, not single-file ODF XML documents.

Constructor Summary

OdtMerger()
Constructs an OdtMerger.

Method Summary

void	finalise(File mergeResult, File finalisedDoc) Finalises a merge result file.
void	finalise(File mergeResult, File finalisedDoc, boolean acceptChanges) Finalises a merge result file.
void	finalise(File mergeResult, File finalisedDoc, boolean acceptChanges, ClassLoader cl) Finalises a merge result file.
void	finalise(File mergeResult, OutputStream finalisedDoc, boolean acceptChanges, ClassLoader cl) Finalises a merge result file.
static String	getVersion() Returns the version of the OdtMerger currently in use.
void	merge(File base, List<File> edits, File result) Merges two or more ODT files and produces an ODT result that contains changes relative to the base file as tracked-changes.
void	merge(File base, List<File> edits, File result, ClassLoader cl) Merges two or more ODT files and produces an ODT result that contains changes relative to the base file as tracked-changes.
void	merge(File base, List<File> edits, OutputStream result, ClassLoader cl) Merges two or more ODT files and produces an ODT result that contains changes relative to the base file as tracked-changes.
void	setAddedBackground(Color color) Sets the background color of the text marked as added in an individual editor's version of a merge-unit
void	setAddedColor(Color color) Sets the color of the text marked as added in an individual editor's version of a merge-unit
void	setAddedDecoration(FontDecoration decoration) Sets the font decoration of the text marked as added in an individual editor's version of a merge-unit.
void	setAddedStyle(FontStyle style) Sets the font style of the text marked as added in an individual editor's version of a merge-unit.
void	setAddedWeight(FontWeight weight) Sets the font weight of the text marked as added in an individual editor's version of a merge-unit.
void	setDeletedBackground(Color color) Sets the background color of the text marked as deleted in an individual editor's version of a merge-unit
void	setDeletedColor(Color color) Sets the color of the text marked as deleted in an individual editor's version of a merge-unit
void	setDeletedDecoration(FontDecoration decoration) Sets the font decoration of the text marked as deleted in an individual editor's version of a merge-unit.
void	setDeletedStyle(FontStyle style) Sets the font style of the text marked as deleted in an individual editor's version of a merge-unit.
void	setDeletedWeight(FontWeight weight) Sets the font weight of the text marked as deleted in an individual editor's version of a merge-unit.
void	setDisplayCharacterStyleChanges(boolean value) Sets whether to display character style changes when comparing edits against the base.
void	setDisplayFrameAttributeChanges(boolean value) Sets whether to display frame attribute changes when comparing edits against the base.
void	setDisplayMergeUnitStyleChanges(boolean value) Sets whether to display merge-unit style changes when comparing edits against the base.
void	setEditBackgroundColor(Color color) Sets the background color to use to mark edit sections.
void	setEditorColor(Color color) Sets the color to use for text that describes an editor's change.
void	setEditorDecoration(FontDecoration decoration) Sets the font decoration to use for text that describes an editors change.
void	setEditorStyle(FontStyle style) Sets the font style to use for text that describes an editors change.
void	setEditorWeight(FontWeight weight) Sets the font weight to use for text that describes an editors change.
void	setEditOutput(EditOutput value) Sets which EditOutput option to use in the result.
void	setExtendibleResult(boolean value) Sets whether the merge result should be extendible with more versions.
void	setImageEditOutput(ImageEditOutput value) Sets which ImageEditOutput option to use in the result.
void	setKeyTablesByName(boolean value) Sets whether or not to use table names as keys for table alignment.

Methods inherited from class java.lang.Object

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

Constructor Detail

OdtMerger

public OdtMerger()
          throws OdtMergerConfigurationException

Constructs an OdtMerger. If necessary, the Object should then be configured by calling the various set methods to set the desired parameters before calling one of the merge methods.

Throws:

OdtMergerConfigurationException - when there is a problem configuring the OdtMerger. This could be caused by the wrong version of Saxon being available on the classpath.

Method Detail

getVersion

public static String getVersion()

Returns the version of the OdtMerger currently in use.

Returns:

a String representing the version number of this version of the OdtMerger

setDisplayMergeUnitStyleChanges

public void setDisplayMergeUnitStyleChanges(boolean value)

Sets whether to display merge-unit style changes when comparing edits against the base.

Merge-unit style changes are not shown as tracked changes in the result file so this setting only has an effect if individual editors' changes are being shown in edit sections. If they are, passing a value of true to this method will cause an edit section to be displayed for merge-units that have had their style changed. The edit unit will use the style specified in the editor's version of the document.

Default: false - these style changes are not displayed

Parameters:

value - a boolean stating whether to display merge-unit style changes

See Also:

setEditOutput(EditOutput)

setDisplayCharacterStyleChanges

public void setDisplayCharacterStyleChanges(boolean value)

Sets whether to display character style changes when comparing edits against the base.

Character-level style changes are not shown as tracked changes in the result file so this setting only has an effect if individual editors' changes are being shown in edit sections. If they are, passing a value of true to this method will cause an edit section to be displayed when the style of individual words or characters is changed within a merge unit. The edit unit will use the style specified in the editor's version of the document.

Default: false - these style changes are not displayed

Parameters:

value - a boolean stating whether or not to display character style changes

setDisplayFrameAttributeChanges

public void setDisplayFrameAttributeChanges(boolean value)

Sets whether to display frame attribute changes when comparing edits against the base.

Changes to the size, position and z-index of frames containing text boxes, images or objects are not shown as tracked changes in the result file so this setting only has effect if individual editors' changes are being shown in edit sections. If they are,passing a value of true to this method will cause an edit section to be displayed when a frame's attributes change.

Default: false - frame attribute changes are not displayed

Parameters:

value - a boolean stating whether or not to display frame attribute changes

setEditBackgroundColor

public void setEditBackgroundColor(Color color)

Sets the background color to use to mark edit sections.

Edit sections can be marked with this background color to distinguish them from the main parts of the document.

Note: only the RGB value of the Color will be used, any Alpha component will be ignored.

Default: the Color with the RGB value 999999

Parameters:

color - the Color to use to mark edit sections

setEditorColor

public void setEditorColor(Color color)

Sets the color to use for text that describes an editor's change.

If edit sections are being displayed, the Color of the text that describes the change that has taken place and details of who performed the change can be set using this method.

Note: only the RGB value of the Color will be used, any Alpha component will be ignored.

Default: the Color with the RGB value 0000FF

Parameters:

color - the Color used for edit section text

setEditorWeight

public void setEditorWeight(FontWeight weight)

Sets the font weight to use for text that describes an editors change.

If edit sections are being displayed, the FontWeight of the text that describes the change that has taken place and details of who performed the change can be set using this method.

Default: FontWeight.NONE

Parameters:

weight - the FontWeight used for edit section text

setEditorStyle

public void setEditorStyle(FontStyle style)

Sets the font style to use for text that describes an editors change.

If edit sections are being displayed, the FontStyle of the text that describes the change that has taken place and details of who performed the change can be set using this method.

Default: FontStyle.ITALIC

Parameters:

style - the FontStyle used for edit section text

setEditorDecoration

public void setEditorDecoration(FontDecoration decoration)

Sets the font decoration to use for text that describes an editors change.

If edit sections are being displayed, the FontDecoration of the text that describes the change that has taken place and details of who performed the change can be set using this method.

Default: FontDecoration.NONE

Parameters:

decoration - the FontDecoration used for edit section text

setAddedColor

public void setAddedColor(Color color)

Sets the color of the text marked as added in an individual editor's version of a merge-unit

Note: only the RGB value of the Color will be used, any Alpha component will be ignored.

Default: none, i.e. the added text takes its color from its style as defined in the editor's version of the document.

Parameters:

color - the Color whose RGB value will be used for added text

setAddedWeight

public void setAddedWeight(FontWeight weight)

Sets the font weight of the text marked as added in an individual editor's version of a merge-unit.

Default: FontWeight.NONE

Parameters:

weight - the FontWeight to be used for added text

See Also:

FontWeight

setAddedStyle

public void setAddedStyle(FontStyle style)

Sets the font style of the text marked as added in an individual editor's version of a merge-unit.

Default: FontStyle.NONE

Parameters:

style - the FontStyle to be used for added text

See Also:

FontStyle

setAddedDecoration

public void setAddedDecoration(FontDecoration decoration)

Sets the font decoration of the text marked as added in an individual editor's version of a merge-unit.

Default: FontDecoration.NONE

Parameters:

decoration - the FontDecoration to be used for added text

See Also:

FontDecoration

setAddedBackground

public void setAddedBackground(Color color)

Sets the background color of the text marked as added in an individual editor's version of a merge-unit

Note: only the RGB value of the Color will be used, any Alpha component will be ignored.

Default: the Color with RGB value 90EE90 (light green)

Parameters:

color - the Color whose RGB value will be used for the background to added text

setDeletedColor

public void setDeletedColor(Color color)

Sets the color of the text marked as deleted in an individual editor's version of a merge-unit

Note: only the RGB value of the Color will be used, any Alpha component will be ignored.

Default: none, i.e. the deleted text takes its color from its style as defined in the editor's version of the document.

Parameters:

color - the Color whose RGB value will be used for deleted text

setDeletedWeight

public void setDeletedWeight(FontWeight weight)

Sets the font weight of the text marked as deleted in an individual editor's version of a merge-unit.

Default: FontWeight.NONE

Parameters:

weight - the FontWeight to be used for deleted text

See Also:

FontWeight

setDeletedStyle

public void setDeletedStyle(FontStyle style)

Sets the font style of the text marked as deleted in an individual editor's version of a merge-unit.

Default: FontStyle.NONE

Parameters:

style - the FontStyle to be used for deleted text

See Also:

FontStyle

setDeletedDecoration

public void setDeletedDecoration(FontDecoration decoration)

Sets the font decoration of the text marked as deleted in an individual editor's version of a merge-unit.

Default: FontDecoration.STRIKETHROUGH

Parameters:

decoration - the FontDecoration to be used for deleted text

See Also:

FontDecoration

setDeletedBackground

public void setDeletedBackground(Color color)

Sets the background color of the text marked as deleted in an individual editor's version of a merge-unit

Note: only the RGB value of the Color will be used, any Alpha component will be ignored.

Default: the Color with RGB value FF5555 (light red)

Parameters:

color - the Color whose RGB value will be used for the background to deleted text

setExtendibleResult

public void setExtendibleResult(boolean value)

Sets whether the merge result should be extendible with more versions.

A merge result can optionally be extended with more documents derived from the base at a later stage. This method allows the user to specify whether this should be possible with the result produced. Passing a value of false to this method (i.e stating that the result will not be extendible) may improve the speed of the merge.

Default: true

Parameters:

value - whether the result should be extendible or not

setEditOutput

public void setEditOutput(EditOutput value)

Sets which EditOutput option to use in the result.

When a merge unit change occurs, the result contains the change in tracked change format (where the format allows). An optional edit unit can also be output that shows just an individual editor's changes. This method is used to set which type of output is used when generating the result. See EditOutput for more details.

Parameters:

value - the EditOutput type to use in the result

See Also:

EditOutput, setImageEditOutput(ImageEditOutput)

setImageEditOutput

public void setImageEditOutput(ImageEditOutput value)

Sets which ImageEditOutput option to use in the result.

Because image an object changes cannot always be displayed using tracked changes in all ODT viewers/editors, changes to them may only be noticeable using edit units. Thus, control of the edit units for images and objects is separate from that for other merge unit types and is controlled using this method. See ImageEditOutput for more details.

Parameters:

value - the ImageEditOutput type to use in the result

See Also:

ImageEditOutput, setEditOutput(EditOutput)

setKeyTablesByName

public void setKeyTablesByName(boolean value)

Sets whether or not to use table names as keys for table alignment.

Parameters:

value - whether to use table names as keys

merge

public void merge(File base,
                  List<File> edits,
                  File result)
           throws FileNotFoundException,
                  OdtMergerException,
                  InvalidOdtFileException,
                  NonExtendibleMergeResultException,
                  OdtInputException,
                  OdtOutputException,
                  StylesheetLoadException,
                  OdfLicensingException

Merges two or more ODT files and produces an ODT result that contains changes relative to the base file as tracked-changes.

Uses the context ClassLoader (that returned by : Thread.getContextClassLoader() called from the result of Thread.currentThread()) to locates resources it needs during the merge. See the other merge methods if an alternative ClassLoader is required due to application server or IDE restrictions.

Parameters:

base - the base File against which all other inputs are compared

edits - the List of edit Files that are compared against the base

result - specifies an ODT File which will be created to contain the tracked changes

Throws:

FileNotFoundException - if the input files or the result destination cannot be located

OdtMergerException - if there is a problem during the merge. See the nested cause for more information

InvalidOdtFileException - if one of the input files is not an ODT file in the expected packaging format

NonExtendibleMergeResultException - if the base file is a merge result that cannot be extended

OdtInputException - if there is a problem reading one of the input files

OdtOutputException - if there is a problem writing to the output file

StylesheetLoadException - if a required stylesheet cannot be loaded. See the exception documentation for more details

OdfLicensingException - if there is a problem with the software license. NB the actual exception thrown will be a sub-type of OdfLicensingException. See the exception documentation for more details

merge

public void merge(File base,
                  List<File> edits,
                  File result,
                  ClassLoader cl)
           throws FileNotFoundException,
                  OdtMergerException,
                  InvalidOdtFileException,
                  NonExtendibleMergeResultException,
                  OdtInputException,
                  OdtOutputException,
                  StylesheetLoadException,
                  OdfLicensingException

Merges two or more ODT files and produces an ODT result that contains changes relative to the base file as tracked-changes.

Parameters:

base - the base File against which all other inputs are compared

edits - the List of edit Files that are compared against the base

result - specifies an ODT File which will be created to contain the tracked changes

cl - the ClassLoader used to locate resources during the merge

Throws:

FileNotFoundException - if the input files or the result destination cannot be located

OdtMergerException - if there is a problem during the merge. See the nested cause for more information

InvalidOdtFileException - if one of the input files is not an ODT file in the expected packaging format

NonExtendibleMergeResultException - if the base file is a merge result that cannot be extended

OdtInputException - if there is a problem reading one of the input files

OdtOutputException - if there is a problem writing to the output file

StylesheetLoadException - if a required stylesheet cannot be loaded. See the exception documentation for more details

OdfLicensingException - if there is a problem with the software license. NB the actual exception thrown will be a sub-type of OdfLicensingException. See the exception documentation for more details

merge

public void merge(File base,
                  List<File> edits,
                  OutputStream result,
                  ClassLoader cl)
           throws OdtMergerException,
                  InvalidOdtFileException,
                  NonExtendibleMergeResultException,
                  OdtInputException,
                  OdtOutputException,
                  StylesheetLoadException,
                  OdfLicensingException

Merges two or more ODT files and produces an ODT result that contains changes relative to the base file as tracked-changes.

Parameters:

base - the base File against which all other inputs are compared

edits - the List of edit Files that are compared against the base

result - specifies an OutputStream which will be used as the basis for a ZipOutputStream to which to write the result that contains the tracked changes

cl - the ClassLoader used to locate resources during the merge

Throws:

OdtMergerException - if there is a problem during the merge. See the nested cause for more information

InvalidOdtFileException - if one of the input files is not an ODT file in the expected packaging format

NonExtendibleMergeResultException - if the base file is a merge result that cannot be extended

OdtInputException - if there is a problem reading one of the input files

OdtOutputException - if there is a problem writing to the output

StylesheetLoadException - if a required stylesheet cannot be loaded. See the exception documentation for more details

OdfLicensingException - if there is a problem with the software license. NB the actual exception thrown will be a sub-type of OdfLicensingException. See the exception documentation for more details

finalise

public void finalise(File mergeResult,
                     File finalisedDoc)
              throws FileNotFoundException,
                     OdtMergerException,
                     InvalidOdtFileException,
                     OdtInputException,
                     OdtOutputException,
                     StylesheetLoadException

Finalises a merge result file. This means that all units showing an individual editor's changes are removed and merge metadata is also removed.

Note: The result file produced by this operation can no longer have edited versions added to it.

Parameters:

mergeResult - a File that is the result of running merge on two or more input documents

finalisedDoc - a File in which to write the finalised document

Throws:

FileNotFoundException - if the result file cannot be created

OdtMergerException - if there is a problem during the operation. See the nested cause for more information

InvalidOdtFileException - if the input file is not an ODT file in the expected packaging format

OdtInputException - if there is a problem reading the input file

OdtOutputException - if there is a problem writing to the output file

StylesheetLoadException - if a required stylesheet cannot be loaded. See the exception documentation for more details

finalise

public void finalise(File mergeResult,
                     File finalisedDoc,
                     boolean acceptChanges)
              throws FileNotFoundException,
                     OdtMergerException,
                     InvalidOdtFileException,
                     OdtInputException,
                     OdtOutputException,
                     StylesheetLoadException

Finalises a merge result file. This means that all units showing an individual editor's changes are removed and merge metadata is also removed. Any remaining tracked changes can optionally be automatically accepted.

Note: The result file produced by this operation can no longer have edited versions added to it.

Parameters:

mergeResult - a File that is the result of running merge on two or more input documents

finalisedDoc - a File in which to write the finalised document

acceptChanges - whether or not to accept any remaining changes in the document

Throws:

FileNotFoundException - if the result file cannot be created

OdtMergerException - if there is a problem during the operation. See the nested cause for more information

InvalidOdtFileException - if the input file is not an ODT file in the expected packaging format

OdtInputException - if there is a problem reading the input file

OdtOutputException - if there is a problem writing to the output file

StylesheetLoadException - if a required stylesheet cannot be loaded. See the exception documentation for more details

finalise

public void finalise(File mergeResult,
                     File finalisedDoc,
                     boolean acceptChanges,
                     ClassLoader cl)
              throws FileNotFoundException,
                     OdtMergerException,
                     InvalidOdtFileException,
                     OdtInputException,
                     OdtOutputException,
                     StylesheetLoadException

Finalises a merge result file. This means that all units showing an individual editor's changes are removed and merge metadata is also removed. Any remaining tracked changes can optionally be automatically accepted.

Note: The result file produced by this operation can no longer have edited versions added to it.

Parameters:

mergeResult - a File that is the result of running merge on two or more input documents

finalisedDoc - a File in which to write the finalised document

acceptChanges - whether or not to accept any remaining changes in the document

cl - the ClassLoader used to locate resources during the operation

Throws:

FileNotFoundException - if the result file cannot be created

OdtMergerException - if there is a problem during the operation. See the nested cause for more information

InvalidOdtFileException - if the input file is not an ODT file in the expected packaging format

OdtInputException - if there is a problem reading the input file

OdtOutputException - if there is a problem writing to the output file

StylesheetLoadException - if a required stylesheet cannot be loaded. See the exception documentation for more details

finalise

public void finalise(File mergeResult,
                     OutputStream finalisedDoc,
                     boolean acceptChanges,
                     ClassLoader cl)
              throws OdtMergerException,
                     InvalidOdtFileException,
                     OdtInputException,
                     OdtOutputException,
                     StylesheetLoadException

Finalises a merge result file. This means that all units showing an individual editor's changes are removed and merge metadata is also removed. Any remaining tracked changes can optionally be automatically accepted.

Note: The result file produced by this operation can no longer have edited versions added to it.

Parameters:

mergeResult - a File that is the result of running merge on two or more input documents

finalisedDoc - specifies an OutputStream which will be used as the basis for a ZipOutputStream to which to write the finalised document.

acceptChanges - whether or not to accept any remaining changes in the document

cl - the ClassLoader used to locate resources during the operation

Throws:

OdtMergerException - if there is a problem during the operation. See the nested cause for more information

InvalidOdtFileException - if the input file is not an ODT file in the expected packaging format

OdtInputException - if there is a problem reading the input file

OdtOutputException - if there is a problem writing to the output

StylesheetLoadException - if a required stylesheet cannot be loaded. See the exception documentation for more details