Aspose.Words for Java 21.1 Release Notes

Major Features

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

  • StartColumnBookmark and EndColumnBookmark methods were introduced in DocumentBuilder class.
  • MarkdownSaveOptions.ImageSavingCallback has been added to control how images are saved upon converting to Markdown format.
  • Added an ability to ignore <noscript> HTML elements upon loading HTML.
  • TableStyle.VerticalAlignment was exposed publicly.

Full List of Issues Covering all Changes in this Release

KeySummaryCategory
WORDSNET-4987Support “cold” rendering of OOXML SmartArt (Diagrams)New Feature
WORDSNET-20666Add feature to create Move revisionNew Feature
WORDSNET-21389Add IImageSavingCallback into MarkdownSaveOptionsNew Feature
WORDSNET-17026LINQ Reporting Engine - Support section breaks inside data bands and conditional blocksNew Feature
WORDSNET-20367Add a field to the Node class so a User can store some custom meta-data in Aspose.Words Document modelNew Feature
WORDSNET-18882Add feature to bookmark the table’s columnNew Feature
WORDSNET-21114Add feature to get or set Cell Vertical Alignment using TableStyleNew Feature
WORDSNET-21426MS Word should automatically pick default Icon of Inserted OLE ObjectEnhancement
WORDSNET-21576Add LastChild property and AppendChild() method to StructuredDocumentRangeStart classEnhancement
WORDSNET-21433Improve URI processing to handle relative hyperlinkEnhancement
WORDSNET-21493Convert Word to JSON in Parent Child HierarchyEnhancement
WORDSJAVA-2435DOCX to PDF conversion issue with David font renderingBug
WORDSJAVA-2470java.lang.RuntimeException is thrown while loading DOCXBug
WORDSJAVA-2475Can’t import drawing shapes from Odt document.Bug
WORDSJAVA-2483Wrong JAR published - Aspose.Words for Java 20.10 (JDK1.6 only)Bug
WORDSJAVA-2501The last letter is missed while rendering Arabic docx to xps using Harfbazz.Bug
WORDSJAVA-2504Direction test failed with NullPointerExceptionBug
WORDSNET-20881Partial rendering of Arabic Words in PDFBug
WORDSNET-21005Document.PageCount hangs for MHTML file generated by Aspose.EmailBug
WORDSNET-18933DOCX to PDF conversion issue with math equationBug
WORDSNET-15142Incorrect page count detectionBug
WORDSNET-21516First column content spilling into second column in PDFBug
WORDSNET-17876Characters (subset) in charts are not rendered in output PDFBug
WORDSNET-13179DOCX to PDF conversion issue with text rendering of Cambodian Fonts “Khmer”Bug
WORDSNET-18333Superscript and Subscript characters in picture are not retained in PDFBug
WORDSNET-21191InvalidOperationException occurs during saving to HTMLBug
WORDSNET-16704BitonalConvertor gives not the same result as on .NETBug
WORDSNET-17362Brackets and equation rendering issue in output PDFBug
WORDSNET-21509DOCX to PDF conversion exception: System.ArgumentOutOfRangeExceptionBug
WORDSNET-21415Document.Compare generates the incorrect outputBug
WORDSNET-17888Arabic characters are improperly rendered to another fontBug
WORDSNET-17986Position of BookmarkStart and BookmarkEnd nodes is changed in output DOCXBug
WORDSNET-21534Incorrect value of STYLEREF field in header - Word to PDF ConversionBug
WORDSNET-21535Aspose.Words.FileCorruptedException is thrown for DOCBug
WORDSNET-21462DOCX to HTML conversion fails with Stack empty error messageBug
WORDSNET-21506Hidden runs located in a Structured Document tag cannot be iteratedBug
WORDSNET-20715The conversion to PDF never endsBug
WORDSNET-21510System.ArgumentOutOfRangeException occurs upon saving to PDFBug
WORDSNET-21519DOCX to PDF conversion exceptionBug
WORDSNET-21494Document.UpdateFields throws NullReferenceExceptionBug
WORDSNET-20010Infinity loop in FloaterOverlapResolver due to zero height floating tableBug
WORDSNET-21545Add obfuscation check to ApiTests.License.Net taskBug
WORDSNET-21552Incorrect identification of list level and list itemBug
WORDSNET-17735Certain Arabic characters are wrong when converting DOCX to PDFBug
WORDSNET-20166Infinity loop in FloaterOverlapResolverBug
WORDSNET-18940Conversion issue DOC/DOCX to PDFBug
WORDSNET-17428Superscript and Subscript characters in Picture render as question mark in PDFBug
WORDSNET-21579Insert SVG image failed on .NetFrameworkBug
WORDSNET-21434DOCX to PDF conversion: The numbering issue in the outputBug
WORDSNET-21253Unexpected chart typeBug
WORDSNET-20876SmartArt to PNG conversion issue with wrong background color and wrong fontBug
WORDSNET-21443LINQ Reporting Engine - An issue with a JSON object having only complex propertiesBug
WORDSNET-20892ODT to Html: Frame borders and position are lost when converting .odt to htmlBug
WORDSNET-21116PDF/A-1a fails accessibility checkBug
WORDSNET-3814Line numbering shows up in OpenOffice after changing PageSetup settingsBug
WORDSNET-21419Inline ole shape overlaps container cell border after DOCX to PDF conversionBug
WORDSNET-21325Comments date do not reflect to changed time zoneBug
WORDSNET-21453“Arithmetic operation resulted in an overflow.” exception when converting DOCX file to PNG/HTML/PDFBug
WORDSNET-20954Table lost formatting on page extractionBug
WORDSNET-21268DOC to PDF conversion hangsBug
WORDSNET-21460Bibliography text disappears during conversionBug
WORDSNET-21153UpdatePageLayout is throwing Array Dimensions exceeded supported rangeBug
WORDSNET-20681OutOfMemoryException when SaveAs document as PNGBug
WORDSNET-21173No content is loaded from a CHM fileBug
WORDSNET-21282Preserve Text Alignment in Table Cell during Word DOT to HTML ConversionBug
WORDSNET-21286DataLabel customization does not work when chart is inserted into templateBug
WORDSNET-21171FileCorruptedException is thrown when trying to load a CHM documentBug
WORDSNET-21299Sunburst Chart DOCX to PDF - System.ArgumentException Unexpected chart typeBug
WORDSNET-21476Aspose.Words corrupts document containing statistical chartBug
WORDSNET-21481Comment.DateTime get time in UTC without conversion to localBug
WORDSNET-21326Execution of the Aspose.Words hangs on Linux when Tahoma font is absentBug
WORDSNET-21203HTML to PDF output incompleteBug
WORDSNET-213413rd level of Thai text is not shown and replaced by strange symbol - DOCX to PDFBug
WORDSNET-19932Number list issues while converting DOCX -> HTML -> DOCXBug
WORDSNET-21216Diffrent behavior of “=SUM(ABOVE)” compared to Microsoft WordBug
WORDSNET-21366DOC->PDF conversion: Heading loses capitalization and bold effect in the outputBug
WORDSNET-16770Image’s text is rendered as “?” mark in output PDFBug
WORDSNET-14872Lack of CSS background images while converting from HTML to WordBug
WORDSNET-16336Khmer Mondulkiri font renders incorrectlyBug
WORDSNET-17887Arial Font is used instead of Calibri Fonts during DOCM to PDF conversionBug
WORDSNET-16703TestRadialGradient is rendered improperly.Bug
WORDSNET-11650System.NullReferenceException is thrown while saving DOCX to PDFBug
WORDSNET-19294TestLoadPerformanceLarge() performance test failsBug
WORDSNET-16717Background in MHT looks differentlyBug

Public API and Backward Incompatible Changes

This section lists public API changes that were introduced in Aspose.Words 21.1. 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 a new public property HtmlLoadOptions.IgnoreNoscriptElements

Related issue: WORDSNET-21203

Added a new public property HtmlLoadOptions.IgnoreNoscriptElements:

/// <summary>
/// Gets or sets a value indicating whether to ignore &lt;noscript&gt; HTML elements.
/// Default value is <c>false</c>.
/// </summary>
/// <remarks>
/// Like MS Word, Aspose.Words does not support scripts and by default loads content of &lt;noscript&gt; elements
/// into the resulting document. In most browsers, however, scripts are supported and content from &lt;noscript&gt;
/// is not visible. Setting this property to <c>true</c> forces Aspose.Words to ignore all &lt;noscript&gt; elements
/// and helps to produce documents that look closer to what is seen in browsers.
/// </remarks>
public bool IgnoreNoscriptElements { get; set; }

Customers may now instruct Aspose.Words to ignore <noscript> HTML elements like most modern browsers do.

Use Case:

HtmlLoadOptions loadOptions = new HtmlLoadOptions();
loadOptions.IgnoreNoscriptElements = true;

Added a new public property Node.CustomNodeId

Related issue: WORDSNET-21203

Added a new public property Node.CustomNodeId:

/// <summary>
/// Specifies custom node identifier.
/// </summary>
/// <remarks>
/// <p>Default is zero.</p>
/// <p>This identifier can be set and used arbitrarily. For example, as a key to get external data.</p>
/// </remarks>
public int CustomNodeId { get; set; }

Customers now may track node position in the model tree and bind external data based on assigned identifier:

Use Case:

DocumentBuilder builder = new DocumentBuilder();
Shape shape = builder.InsertShape(ShapeType.Rectangle, 100, 100);
shape.CustomNodeId = 100;

Added a new public property TableStyle.VerticalAlignment

Related issue: WORDSNET-21114

Added a new public options that allows to set table style cell vertical alignment.

/// <summary>
/// Specifies the vertical alignment for the cells.
/// </summary>
/// <remarks>
/// The default value is <see cref="CellVerticalAlignment.Top"/>.
/// </remarks>
public CellVerticalAlignment VerticalAlignment { get; set; }

Use Case:

Document doc = TestUtil.Open(fileName);
TableStyle style = (TableStyle)doc.Styles\["Custom Table 1"\];
style.VerticalAlignment = CellVerticalAlignment.Center;

Added new public methods StartColumnBookmark and EndColumnBookmark to DocumentBuilder class

Related issue: WORDSNET-18882

The following public methods have been added to the DocumentBuilder class:

/// <summary>
/// Marks the current position in the document as a column bookmark start. The position must be in a table cell.
/// </summary>
/// <remarks>
/// <p>A column bookmark covers one or more columns in a range of rows. To create a valid bookmark you
/// need to call both <see cref="StartColumnBookmark"/> and <see cref="EndColumnBookmark"/> with the same
/// <b>bookmarkName</b> parameter.</p>
/// <p>Badly formed bookmarks or bookmarks with duplicate names will be ignored when the document is saved.</p>
/// <p>The actual position of the inserted <see cref="BookmarkStart"/> node may differ from the current document
/// builder position.</p>
/// </remarks>
/// <param name="bookmarkName">Name of the bookmark.</param>
/// <returns>The bookmark start node that was just created.</returns>
public BookmarkStart StartColumnBookmark(string bookmarkName)
 
/// <summary>
/// Marks the current position in the document as a column bookmark end. The position must be in a table cell.
/// </summary>
/// <remarks>
/// <p>A column bookmark covers one or more columns in a range of rows. To create a valid bookmark you
/// need to call both <see cref="StartColumnBookmark"/> and <see cref="EndColumnBookmark"/> with the same
/// <b>bookmarkName</b> parameter.</p>
/// <p>Badly formed bookmarks or bookmarks with duplicate names will be ignored when the document is saved.</p>
/// <p>The actual position of the inserted <see cref="BookmarkEnd"/> node may differ from the current document
/// builder position.</p>
/// </remarks>
/// <param name="bookmarkName">Name of the bookmark.</param>
/// <returns>The bookmark end node that was just created.</returns>
public BookmarkEnd EndColumnBookmark(string bookmarkName)

Use Case:

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
 
builder.StartTable();
 
builder.InsertCell();
builder.StartColumnBookmark("Bookmark1");
builder.Write("Cell 1");
 
builder.InsertCell();
builder.Write("Cell 2");
 
builder.InsertCell();
builder.Write("Cell 3");
 
builder.EndRow();
 
builder.InsertCell();
builder.Write("Cell 4");
 
builder.InsertCell();
builder.Write("Cell 5");
builder.EndColumnBookmark("Bookmark1");
 
builder.InsertCell();
builder.Write("Cell 6");
 
builder.EndRow();
builder.EndTable();
 
doc.Save(dir + "out.docx");

MarkdownSaveOptions.ImageSavingCallback has been added to control how images are saved upon converting to Markdown format

Related issue: WORDSNET-21389

A new public property ‘ImageSavingCallback’ has been added to the ‘MarkdownSaveOptions’ class:

/// <summary>
/// Allows to control how images are saved when a document is saved to <see cref="SaveFormat.Markdown"/> format.
/// </summary>
public IImageSavingCallback ImageSavingCallback

Use Case: Explains how to use ‘MarkdownSaveOptions.ImageSavingCallback’ when saving a document to markdown format

public void HandleDocument()
{
    const string outFileName = "SavingCallback.DocumentParts.Rendering.md";
 
    // Open a document to be converted to Markdown.
    Document doc = new Document("C:\\Rendering.docx");
 
    // We can use an appropriate SaveOptions subclass to customize the conversion process.
    MarkdownSaveOptions options = new MarkdownSaveOptions();
 
    // If we convert a document that contains images into Markdown, we will end up with one Markdown file which links to several images.
    // Each image will be in the form of a file in the local file system.
    // There is also a callback that can customize the name and file system location of each image.
    options.ImageSavingCallback = new SavedImageRename(outFileName);
 
    // The ImageSaving() method of our callback will be run at this time.
    doc.Save($"C:\\{outFileName}", options);
}

/// <summary>
/// Renames saved images that are produced when an Markdown document is saved.
/// </summary>
public class SavedImageRename : IImageSavingCallback
{
    public SavedImageRename(string outFileName)
    {
        mOutFileName = outFileName;
    }
 
    void IImageSavingCallback.ImageSaving(ImageSavingArgs args)
    {
        string imageFileName = $"{mOutFileName} shape {++mCount}, of type {args.CurrentShape.ShapeType}{Path.GetExtension(args.ImageFileName)}";
 
        args.ImageFileName = imageFileName;
        args.ImageStream = new FileStream($"C:\\{imageFileName}", FileMode.Create);
 
        Assert.True(args.ImageStream.CanWrite);
        Assert.True(args.IsImageAvailable);
        Assert.False(args.KeepImageStreamOpen);
    }
 
    private int mCount;
    private readonly string mOutFileName;
}

PdfSaveOptions.EscapeUri is marked as obsolete

We made several improvements in export of hyperlinks to PDF per WORDSNET-21443. Now the cases when setting PdfSaveOptions.EscapeUri to false was required (improper unescaping of explicitly escaped URI delimiter chars) are handled well by default. Thus we do not see a reason to keep this option longer and marked it as obsolete.

/// <summary>
/// A flag specifying whether URI should be escaped before writing.
/// </summary>
/// <remarks>
/// Note that if this option is set to <c>false</c> hyperlinks are written "as is",
/// so valid (escaped) URI should be provided in document's model.
/// <para>The default value is <c>true</c>.</para>
/// </remarks>
[Obsolete("Writing of URI to PDF was improved and cases when disabled escaping was required are handled well now.")]
public bool EscapeUri { get; set; }

Removed obsolete properties FixedPageSaveOptions.PageIndex, FixedPageSaveOptions.PageCount, ImageSaveOptions.PageIndex, ImageSaveOptions.PageCount

Related issue: WORDSNET-21154

Deprecated properties related to page specification when printing were removed from the FixedPageSaveOptions and ImageSaveOptions classes.

[Obsolete("This property is obsolete. Please use PageSet property instead.")]
public new int PageCount
[Obsolete("This property is obsolete. Please use PageSet property instead.")]
public new int PageIndex

The behavior of DocumentBuilder.InsertOleObject() and DocumentBuilder.InsertOleObjectAsIcon() methods was changed

Related issue: WORDSNET-21426

In cases where the DocumentBuilder.InsertOleObject() and DocumentBuilder.InsertOleObjectAsIcon() methods need to create an icon with a caption, they can use the file extension to define the icon, and can use the filename for the icon caption.

More details:

public Shape InsertOleObject(Stream stream, string progId, bool asIcon, Stream presentation)
If ‘presentation’ is omitted and ‘asIcon’ is set, this overloaded method selects the icon according to ‘progId’ and uses the predefined icon caption.

public Shape InsertOleObject(string fileName, bool isLinked, bool asIcon, Stream presentation)
If ‘presentation’ is omitted and ‘asIcon’ is set, this overloaded method selects the icon according to the file extension and uses the filename for the icon caption.

public Shape InsertOleObject(string fileName, string progId, bool isLinked, bool asIcon, Stream presentation)
If ‘presentation’ is omitted and ‘asIcon’ is set, this overloaded method selects the icon according to ‘progId’ and uses the filename for the icon caption.

public Shape InsertOleObjectAsIcon(Stream stream, string progId, string iconFile, string iconCaption)
If ‘iconFile’ and ‘iconCaption’ are omitted, this overloaded method selects the icon according to ‘progId’ and uses the predefined icon caption.

public Shape InsertOleObjectAsIcon(string fileName, string progId, bool isLinked, string iconFile, string iconCaption)
If ‘iconFile’ and ‘iconCaption’ are omitted, this overloaded method selects the icon according to ‘progId’ and uses the filename for the icon caption.

public Shape InsertOleObjectAsIcon(string fileName, bool isLinked, string iconFile, string iconCaption)
If ‘iconFile’ and ‘iconCaption’ are omitted, this overloaded method selects the icon according to the file extension and uses the filename for the icon caption.

Changed XML comments for ‘iconCaption’ arguments of DocumentBuilder.InsertOleObjectAsIcon() methods:

/// <summary>
/// Inserts an embedded or linked OLE object as icon into the document.
/// Allows to specify icon file and caption. Detects OLE object type using file extension.
/// </summary>
/// <param name="fileName">Full path to the file.</param>
/// <param name="isLinked">
/// If true then linked OLE object is inserted otherwise embedded OLE object is inserted.
/// </param>
/// <param name="iconFile">
/// Full path to the ICO file. If the value is null, Aspose.Words will use a predefined image.
/// </param>
/// <param name="iconCaption">
/// Icon caption. If the value is null, Aspose.Words will use the file name.
/// </param>
/// <returns>Shape node containing Ole object and inserted at the current Builder position.</returns>
public Shape InsertOleObjectAsIcon(string fileName, bool isLinked, string iconFile, string iconCaption)

/// <summary>
/// Inserts an embedded or linked OLE object as icon into the document.
/// Allows to specify icon file and caption. Detects OLE object type using given progID parameter.
/// </summary>
/// <param name="fileName">Full path to the file.</param>
/// <param name="progId">ProgId of OLE object.</param>
/// <param name="isLinked">
/// If true then linked OLE object is inserted otherwise embedded OLE object is inserted.
/// </param>
/// <param name="iconFile">
/// Full path to the ICO file. If the value is null, Aspose.Words will use a predefined image.
/// </param>
/// <param name="iconCaption">
/// Icon caption. If the value is null, Aspose.Words will use the file name.
/// </param>
/// <returns>Shape node containing Ole object and inserted at the current Builder position.</returns>

public Shape InsertOleObjectAsIcon(string fileName, string progId, bool isLinked, string iconFile, string iconCaption)
/// <summary>
/// Inserts an embedded OLE object as icon from a stream into the document.
/// Allows to specify icon file and caption. Detects OLE object type using given progID parameter.
/// </summary>
/// <param name="stream">Stream containing application data.</param>
/// <param name="progId">ProgId of OLE object.</param>
/// <param name="iconFile">
/// Full path to the ICO file. If the value is null, Aspose.Words will use a predefined image.
/// </param>
/// <param name="iconCaption">
/// Icon caption. If the value is null, Aspose.Words will use the a predefined icon caption.
/// </param>
/// <returns>Shape node containing Ole object and inserted at the current Builder position.</returns>
public Shape InsertOleObjectAsIcon(Stream stream, string progId, string iconFile, string iconCaption)

The behavior of revision tracking feature triggered by Document.StartTrackRevisions was changed

Related issue: WORDSNET-20666

When revisions are tracked using Document.StartTrackRevisions, if a node is moved from one location to another in the same document, move revisions are now generated, including move-from and move-to ranges.

Use Case:

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
 
// Generate document contents.
builder.Writeln("Paragraph 1");
builder.Writeln("Paragraph 2");
builder.Writeln("Paragraph 3");
builder.Writeln("Paragraph 4");
builder.Writeln("Paragraph 5");
builder.Writeln("Paragraph 6");
 
Body body = doc.FirstSection.Body;
 
// Returns 7.
Console.WriteLine("Paragraph count: {0}", body.Paragraphs.Count);
 
doc.StartTrackRevisions("Author", new DateTime(2020, 12, 23, 14, 0, 0));
 
Node node = body.Paragraphs[3];
Node endNode = body.Paragraphs[5].NextSibling;
Node referenceNode = body.Paragraphs[0];
 
while (node != endNode)
{
    Node nextNode = node.NextSibling;
    body.InsertBefore(node, referenceNode);
    node = nextNode;
}
 
doc.StopTrackRevisions();
 
// Returns 10: there are 3 additional paragraphs in the move-from range.
Console.WriteLine("Paragraph count: {0}", body.Paragraphs.Count);
 
doc.Save(dir + @"out.docx");