Aspose.Words for Java 21.8 Release Notes

Major Features

There are 82 improvements and fixes in this regular monthly release. The most notable are:

  • Added an ability to insert GIF images into the document.
  • Added new Pdf save option - ExportLanguageToSpanTag.
  • Implemented field updating public callback.

Full List of Issues Covering all Changes in this Release

WORDSNET-20059Provide API to move cursor to any position (character etc) inside a ParagraphNew Feature
WORDSNET-19311Add support for HSL colors in HTML documentsNew Feature
WORDSNET-19381Add context to exceptions thrown while evaluating expressions for LINQ Reporting EngineNew Feature
WORDSNET-21015Request to Remove Generator or Producer NameNew Feature
WORDSNET-22449Calculate storeItemChecksum attribute on SaveNew Feature
WORDSNET-22345Export language in Tag tab of object propertiesNew Feature
WORDSNET-1786Allow inserting GIF images into the documentNew Feature
WORDSNET-22408Implement field updating public callbackNew Feature
WORDSJAVA-2623Add feature to get certificate valid ‘from’ and ’to’ DatesNew Feature
WORDSNET-22539Opening a document using the Document class is significantly slower in version 21.3 compared to 16.5Enhancement
WORDSJAVA-2508The top parts of Thai symbols are stripped out from EMF output file.Bug
WORDSJAVA-2544File size issue when converting with PdfCompliance.PDF_A_1_A optionBug
WORDSJAVA-2559ReportingEngine.buildReport throws java.lang.IllegalStateExceptionBug
WORDSJAVA-2580Document.getPageCount() throws java.lang.StringIndexOutOfBoundsExceptionBug
WORDSJAVA-2588JsonDataSource issue with namesake Table and Column names.Bug
WORDSJAVA-2603Zero relations in DataSet while parsing JsonDataSource (LINQ Reporting Engine)Bug
WORDSJAVA-2606MHTML to PDF: Some characters not converted properlyBug
WORDSJAVA-2629Css Tokenizer returns -0.0 instead of 0.0Bug
WORDSJAVA-2632CSS namespaces sort order.Bug
WORDSNET-18068Document.UpdateFields does not update RD fieldBug
WORDSNET-8796Hebrew RTL/LTR text is not preserved during saving DOCX to TXTBug
WORDSNET-22352PDF Conversion failing to an error when Shape has a Transparency valueBug
WORDSNET-22354System.ArgumentOutOfRangeException occurs upon Word DOCX to PDF conversionBug
WORDSNET-21828Table list paragraph wrongly updating in word document tableBug
WORDSNET-22365Text is pushed down to next page after DOCX to PDF conversionBug
WORDSNET-22549Unable to detect correct load format of a MHT fileBug
WORDSNET-22375DOCX to PDF conversion issueBug
WORDSNET-22376DOCX to PDF conversion issue PDF is not editableBug
WORDSNET-19735The last horizontal axis label is lost after converting to PDFBug
WORDSNET-19175Chart is cropped in output PNGBug
WORDSNET-19180Line types in Chart mismatch in PDFBug
WORDSNET-19182Chart’s Line type mismatched in PDFBug
WORDSNET-21686HTML to DOCX conversion issue with text layout and positionBug
WORDSNET-19719The ConvertFontSizeToRelativeUnitsIfNeeded raises an exception if font-size is not a length ValueTypeBug
WORDSNET-21873Document comparison: Incorrect redliningBug
WORDSNET-21522DOCX to HTML conversion issue with target frame settingBug
WORDSNET-19950Formatting for some characters does not apply when rendering in PDFBug
WORDSNET-22405LocaleConverter doesn’t have mapping for Language.Breton and Language.Alsatian localesBug
WORDSNET-21098Text is moved to previous page after DOCX to PDF conversionBug
WORDSNET-21449Khmer characters not appearing in PDF - Font: Avenir 85 HeavyBug
WORDSNET-20855Chart does not render correctly in output PDFBug
WORDSNET-20938Empty list paragraph moved to second pageBug
WORDSNET-22410Language of text changes after re-saving a DOCX documentBug
WORDSNET-22414“Pie” and “Doughnut” charts with “Explosion” are rendered incorrectly after converting to PDFBug
WORDSNET-22417Range.Replace with multi-line Regex to detect data in word filesBug
WORDSNET-21925DOCX to HTML Image inside the table cells is not up to the original documentBug
WORDSNET-22421Document.UpdateFields method throws System.ArgumentExceptionBug
WORDSNET-22254Revisions.AcceptAll does not accept revisions correctlyBug
WORDSNET-21365Content are lost after MHTML to PDF conversionBug
WORDSNET-21379Problem with logical structure of irregular tables when exporting to PDFBug
WORDSNET-21409Shape text does not render correctly after DOC to HtmlFixed conversionBug
WORDSNET-22431Chart data labels/axis are wrong when converting DOCX to PDFBug
WORDSNET-22434“Russian (Moldova)” and “Romanian (Moldova)” languages are not correctly loaded and saved from/to DOCX documentsBug
WORDSNET-22269Quotes in Word document aren’t matched by ReplaceBug
WORDSNET-21954Styling is not working when we use builder.InsertHtmlBug
WORDSNET-22446InsertDocument does not preserve HeaderFooters and formatting when inserting into empty sectionBug
WORDSNET-22319Headers and Footers are lost after DOCX to ODT conversionBug
WORDSNET-22452System.NullReferenceException occurs upon DOCX to TIFF conversionBug
WORDSNET-22450Aspose gives FileCorruptedException for RTF but Microsoft Word opens fineBug
WORDSNET-22147DOCX to PDF/a: Empty P tag without contentBug
WORDSNET-22385Document.UpdateFields throws System.ExceptionBug
WORDSNET-22327Image width is decreased after saving document to ODTBug
WORDSNET-22298Linked text box in source document corrupts NodeImporter result in destination documentBug
WORDSNET-21588IReplacingCallback is never executedBug
WORDSNET-22456“IsShowingPlaceholderText” property is wrongBug
WORDSNET-22313FileCorruptedException when loading a documentBug
WORDSNET-22438Option for Include label and number in Table of FiguresBug
WORDSNET-22465DOCX to PDF Conversion issue with chart renderingBug
WORDSNET-22318Section breaks (odd/even ) are changed to ‘continuous’ after DOCX to ODT conversionBug
WORDSNET-22479Header image color changes from pink to blue after appending documentsBug
WORDSNET-22485Need to implement the correct use of fonts in formulasBug
WORDSNET-22448fldinst DATE and TIME are inconsistentBug
WORDSNET-22491Document.PageCount returns incorrect page numbersBug
WORDSNET-22476NullReferenceException is thrown when call UpdatePageLayoutBug
WORDSNET-22499Resource loading takes a long timeBug
WORDSNET-22507Word Document Template - Data Merge Rendering IssueBug
WORDSNET-21830Replacing overlapping Bookmarks behaves unexpected or causes an error with JavaBug
WORDSNET-22353Header and footer lost after replace with section breakBug
WORDSNET-22515Word Table content overlaps footer content in PDFBug
WORDSNET-22534FileCorruptedException is thrown while loading DOCBug
WORDSNET-17892DOCX to HTML conversion issue with space between list number and textBug
WORDSNET-22015PDF generated by Aspose.Words does not conform PDF StandardsBug

Public API and Backward Incompatible Changes

This section lists public API changes that were introduced in Aspose.Words 21.8. It includes not only new and obsoleted public methods, but also a description of any changes in the behavior behind the scenes in Aspose.Words which may affect existing code. Any behavior introduced that could be seen as regression and modifies the existing behavior is especially important and is documented here.

Added ability to insert GIF image into the document

Related issue: WORDSNET-1786

Introduced ability to insert a GIF image into the model using “DocumentBuilder.InsertImage” method.


  • Access to the image bytes causes conversion GIF to PNG;

  • Saving to formats differ from the DOCX, DOTX, DOCM, DOTM, FOPC causes conversion GIF to PNG;

  • DocumentBuilder must be optimized to Word 2007 or higher (Word 2007 is default option).

Use Case: Explains how to insert a GIF image.

DocumentBuilder builder = new DocumentBuilder();
Shape image = builder.InsertImage("image.gif");

Added new Pdf save option - ExportLanguageToSpanTag

The new save option allows to customize how the Lang entry should be exported. It can be useful for compatibility with some screen readers.

/// <summary>
/// Gets or sets a value determining whether or not to create a "Span" tag in the document structure to export the text language.
/// </summary>
/// <remarks>
/// <para> Default value is <c>false</c> and "Lang" attribute is attached to a marked-content sequence in a page content stream.</para>
/// <para> When the value is <c>true</c> "Span" tag is created for the text with non-default language and "Lang" attribute is attached to this tag.</para>
/// <para> This value is ignored when <see cref="ExportDocumentStructure"/> is <c>false</c>. </para>
/// </remarks>
public bool ExportLanguageToSpanTag

Use Case:

Document doc = new Document("input.docx");
PdfSaveOptions options = new PdfSaveOptions();
options.ExportDocumentStructure = true;
options.ExportLanguageToSpanTag = true;
doc.Save("output.pdf", options);

Implemented field updating public callback

Related issue: WORDSNET-22408

As a part of customer driven development, we have implemented a field updating public callback interface:

/// <summary>
/// Implement this interface if you want to have your own custom methods called during a field update.
/// </summary>
public interface IFieldUpdatingCallback
    /// <summary>
    /// A user defined method that is called just before a field is updated.
    /// </summary>
    void FieldUpdating(Field field);
    /// <summary>
    /// A user defined method that is called just after a field is updated.
    /// </summary>
    void FieldUpdated(Field field);

And a FieldOptions property:

/// <summary>
/// Gets or sets <see cref="IFieldUpdatingCallback"/> implementation
/// </summary>
public IFieldUpdatingCallback FieldUpdatingCallback { get; set; }

Use case:

document.FieldOptions.FieldUpdatingCallback = new FieldUpdatingCallback();
public class FieldUpdatingCallback : IFieldUpdatingCallback
    void IFieldUpdatingCallback.FieldUpdating(Field field)
        // Do something on field updating.
    void IFieldUpdatingCallback.FieldUpdated(Field field)
        // Do something on field updated.

Added new public property SaveOptions.FlatOpcXmlMappingOnly

Related issue: WORDSNET-22507

New public FlatOpcXmlMappingOnly option has been implemented.

/// <summary>
/// Gets or sets value determining which document formats are allowed to be mapped by <see cref="StructuredDocumentTag.XmlMapping"/>.
/// By default only <see cref="LoadFormat.FlatOpc"/> document format is allowed to be mapped.
/// </summary>
public bool FlatOpcXmlMappingOnly { get; set; }

By default MS Word allows to bind structured document tags to FlatOpc documents only. This option allows to control this behavior and bind documents in any format.

Use case:

Document doc = new Document("filename"); // a document containing SDT mapped to document, for example, in HTML format
doc.Save("out_1.pdf"); // the default behavior - SDT will contain raw HTML text
SaveOptions so = SaveOptions.CreateSaveOptions(SaveFormat.Pdf);
so.FlatOpcXmlMappingOnly = false;

doc.Save("out_2.pdf", so); // mapped HTML will be parsed and resulting document is inserted into SDT content