com.aspose.words

Constructor Detail

• Document

  public Document()
           throws java.lang.Exception

  Creates a blank Word document.

  The document paper size is Letter by default. If you want to change page setup, use Section.PageSetup.

  After creation, you can use DocumentBuilder to add document content easily.

  Example:

  Shows how to add a formatted run of text to a document using the object model.

  Document doc = new Document();
  
  // Create a new run of text
  Run run = new Run(doc, "Hello");
  
  // Specify character formatting for the run of text
  Font f = run.getFont();
  f.setName("Courier New");
  f.setSize(36.0);
  f.setHighlightColor(Color.YELLOW);
  
  // Append the run of text to the end of the first paragraph
  // in the body of the first section of the document
  doc.getFirstSection().getBody().getFirstParagraph().appendChild(run);

• Document

  public Document(java.lang.String fileName)
           throws java.lang.Exception

  Opens an existing document from a file. Automatically detects the file format.

  Parameters:

  fileName - File name of the document to open.

  Example:

  Shows how to open a document and convert it to .PDF.

  Document doc = new Document(getMyDir() + "Document.docx");
  
  doc.save(getArtifactsDir() + "Document.ConvertToPdf.pdf");

• Document

  public Document(java.lang.String fileName, LoadOptions loadOptions)
           throws java.lang.Exception

  Opens an existing document from a file. Allows to specify additional options such as an encryption password.

  Parameters:

  fileName - File name of the document to open.

  loadOptions - Additional options to use when loading a document. Can be null.

  Example:

  Shows how to create and load documents.

  // There are two ways of creating a Document object using Aspose.Words.
  // 1 -  Create a blank document.
  Document doc = new Document();
  
  // New Document objects by default come with a section, body, and paragraph;
  // the minimal set of nodes required to begin editing.
  doc.getFirstSection().getBody().getFirstParagraph().appendChild(new Run(doc, "Hello world!"));
  
  // 2 -  Load a document that exists in the local file system.
  doc = new Document(getMyDir() + "Document.docx");
  
  // Loaded documents will have contents that we can access and edit.
  Assert.assertEquals("Hello World!", doc.getFirstSection().getBody().getFirstParagraph().getText().trim());
  
  // Some operations that need to occur during loading, such as using a password to decrypt a document,
  // can be done by passing a LoadOptions object when loading the document.
  doc = new Document(getMyDir() + "Encrypted.docx", new LoadOptions("docPassword"));
  
  Assert.assertEquals("Test encrypted document.", doc.getFirstSection().getBody().getFirstParagraph().getText().trim());

  Example:

  Shows how to load an encrypted Microsoft Word document.

  Document doc;
  
      // Aspose.Words throw an exception if we try to open an encrypted document without its password.
      Assert.assertThrows(IncorrectPasswordException.class, () -> new Document(getMyDir() + "Encrypted.docx"));
  
      // When loading such a document, the password is passed to the document's constructor using a LoadOptions object.
      LoadOptions options = new LoadOptions("docPassword");
  
      // There are two ways of loading an encrypted document with a LoadOptions object.
      // 1 -  Load the document from the local file system by filename.
      doc = new Document(getMyDir() + "Encrypted.docx", options);
  
      // 2 -  Load the document from a stream.
      InputStream stream = new FileInputStream(getMyDir() + "Encrypted.docx");
      try
              {
          doc = new Document(stream, options);
  }
      finally { if (stream != null) stream.close(); }

• Document

  public Document(java.io.InputStream stream)
           throws java.lang.Exception

  Opens an existing document from a stream. Automatically detects the file format.

  The document must be stored at the beginning of the stream.

  W

  Parameters:

  stream - Stream where to load the document from.

  Example:

  Shows how to retrieve a document from a URL and saves it to disk in a different format.

  // This is the URL address pointing to where to find the document
  URL url = new URL("https://omextemplates.content.office.net/support/templates/en-us/tf16402488.dotx");
  
  // The easiest way to load our document from the internet is make use of the URLConnection class
  URLConnection webClient = url.openConnection();
  
  // Download the bytes from the location referenced by the URL
  InputStream inputStream = webClient.getInputStream();
  
  // Convert the input stream to a byte array
  int pos;
  ByteArrayOutputStream bos = new ByteArrayOutputStream();
  while ((pos = inputStream.read()) != -1) bos.write(pos);
  
  byte[] dataBytes = bos.toByteArray();
  
  // Wrap the bytes representing the document in memory into a stream object
  ByteArrayInputStream byteStream = new ByteArrayInputStream(dataBytes);
  
  // Load this memory stream into a new Aspose.Words Document
  // The file format of the passed data is inferred from the content of the bytes itself
  // You can load any document format supported by Aspose.Words in the same way
  Document doc = new Document(byteStream);
  
  // Convert the document to any format supported by Aspose.Words and save
  doc.save(getArtifactsDir() + "Document.OpenDocumentFromWeb.docx");

  Example:

  Shows how to load a document using a stream.

  InputStream stream = new FileInputStream(getMyDir() + "Document.docx");
  try {
      Document doc = new Document(stream);
      Assert.assertEquals("Hello World!\\r\\rHello Word!\\r\\r\\rHello World!", doc.getText().trim());
  } finally {
      if (stream != null) stream.close();
  }

• Document

  public Document(java.io.InputStream stream, LoadOptions loadOptions)
           throws java.lang.Exception

  Opens an existing document from a stream. Allows to specify additional options such as an encryption password.

  The document must be stored at the beginning of the stream.

  Parameters:

  stream - The stream where to load the document from.

  loadOptions - Additional options to use when loading a document. Can be null.

  Example:

  Shows how to insert the HTML contents from a web page into a new document.

  // The url of the page to load
  URL url = new URL("http://www.aspose.com/");
  
  // The easiest way to load our document from the internet is make use of the URLConnection class
  URLConnection webClient = url.openConnection();
  
  // Download the bytes from the location referenced by the URL
  InputStream inputStream = webClient.getInputStream();
  
  // Convert the input stream to a byte array
  int pos;
  ByteArrayOutputStream bos = new ByteArrayOutputStream();
  while ((pos = inputStream.read()) != -1) bos.write(pos);
  
  byte[] dataBytes = bos.toByteArray();
  
  // Wrap the bytes representing the document in memory into a stream object
  ByteArrayInputStream byteStream = new ByteArrayInputStream(dataBytes);
  
  // The baseUri property should be set to ensure any relative img paths are retrieved correctly
  LoadOptions options = new LoadOptions(LoadFormat.HTML, "", url.getPath());
  
  // Load the HTML document from stream and pass the LoadOptions object
  Document doc = new Document(byteStream, options);
  
  // Save the document to the local file system while converting it to .docx
  doc.save(getArtifactsDir() + "Document.InsertHtmlFromWebPage.docx");

  Example:

  Shows how to open an HTML document with images from a stream using a base URI.

  InputStream stream = new FileInputStream(getMyDir() + "Document.html");
      try /*JAVA: was using*/
      {
          // Pass the URI of the base folder while loading it
          // so that any images with relative URIs in the HTML document can be found.
          LoadOptions loadOptions = new LoadOptions();
          loadOptions.setBaseUri(getImageDir());
  
          Document doc = new Document(stream, loadOptions);
  
          // Verify that the first shape of the document contains a valid image.
          Shape shape = (Shape)doc.getChild(NodeType.SHAPE, 0, true);
  
      Assert.assertTrue(shape.isImage());
      Assert.assertNotNull(shape.getImageData().getImageBytes());
      Assert.assertEquals(32.0, ConvertUtil.pointToPixel(shape.getWidth()), 0.01);
      Assert.assertEquals(32.0, ConvertUtil.pointToPixel(shape.getHeight()), 0.01);
  }
      finally { if (stream != null) stream.close(); }

  Example:

  Shows how to load an encrypted Microsoft Word document.

  Document doc;
  
      // Aspose.Words throw an exception if we try to open an encrypted document without its password.
      Assert.assertThrows(IncorrectPasswordException.class, () -> new Document(getMyDir() + "Encrypted.docx"));
  
      // When loading such a document, the password is passed to the document's constructor using a LoadOptions object.
      LoadOptions options = new LoadOptions("docPassword");
  
      // There are two ways of loading an encrypted document with a LoadOptions object.
      // 1 -  Load the document from the local file system by filename.
      doc = new Document(getMyDir() + "Encrypted.docx", options);
  
      // 2 -  Load the document from a stream.
      InputStream stream = new FileInputStream(getMyDir() + "Encrypted.docx");
      try
              {
          doc = new Document(stream, options);
  }
      finally { if (stream != null) stream.close(); }

Property Getters/Setters Detail

• getAttachedTemplate/setAttachedTemplate

  public java.lang.String getAttachedTemplate() / public void setAttachedTemplate(java.lang.String value)
  

  Gets or sets the full path of the template attached to the document.

  Empty string means the document is attached to the Normal template.

  Example:

  Shows how to set a default template for documents that do not have attached templates.

  Document doc = new Document();
  
  // Enable automatic style updating, but do not attach a template document.
  doc.setAutomaticallyUpdateStyles(true);
  
  Assert.assertEquals("", doc.getAttachedTemplate());
  
  // Since there is no template document, the document had nowhere to track style changes.
  // Use a SaveOptions object to automatically set a template
  // if a document that we are saving does not have one.
  SaveOptions options = SaveOptions.createSaveOptions("Document.DefaultTemplate.docx");
  options.setDefaultTemplate(getMyDir() + "Business brochure.dotx");
  
  doc.save(getArtifactsDir() + "Document.DefaultTemplate.docx", options);

  See Also:

  BuiltInDocumentProperties.Template

• getAutomaticallyUpdateStyles/setAutomaticallyUpdateStyles

  public boolean getAutomaticallyUpdateStyles() / public void setAutomaticallyUpdateStyles(boolean value)
  

  Gets or sets a flag indicating whether the styles in the document are updated to match the styles in the attached template each time the document is opened in MS Word.

  Example:

  Shows how to attach a template to a document.

  Document doc = new Document();
  
  // Microsoft Word documents by default come with an attached template called "Normal.dotm".
  // There is no default template for blank Aspose.Words documents.
  Assert.assertEquals("", doc.getAttachedTemplate());
  
  // Attach a template, then set the flag to apply style changes
  // within the template to styles in our document.
  doc.setAttachedTemplate(getMyDir() + "Business brochure.dotx");
  doc.setAutomaticallyUpdateStyles(true);
  
  doc.save(getArtifactsDir() + "Document.AutomaticallyUpdateStyles.docx");

  Example:

  Shows how to set a default template for documents that do not have attached templates.

  Document doc = new Document();
  
  // Enable automatic style updating, but do not attach a template document.
  doc.setAutomaticallyUpdateStyles(true);
  
  Assert.assertEquals("", doc.getAttachedTemplate());
  
  // Since there is no template document, the document had nowhere to track style changes.
  // Use a SaveOptions object to automatically set a template
  // if a document that we are saving does not have one.
  SaveOptions options = SaveOptions.createSaveOptions("Document.DefaultTemplate.docx");
  options.setDefaultTemplate(getMyDir() + "Business brochure.dotx");
  
  doc.save(getArtifactsDir() + "Document.DefaultTemplate.docx", options);

• getBackgroundShape/setBackgroundShape

  public Shape getBackgroundShape() / public void setBackgroundShape(Shape value)
  

  Gets or sets the background shape of the document. Can be null.

  Microsoft Word allows only a shape that has its ShapeBase.ShapeType property equal to ShapeType.RECTANGLE to be used as a background shape for a document.

  Microsoft Word supports only the fill properties of a background shape. All other properties are ignored.

  Setting this property to a non-null value will also set the ViewOptions.DisplayBackgroundShape to true.

  Example:

  Shows how to set a background shape for every page of a document.

  Document doc = new Document();
  
  Assert.assertNull(doc.getBackgroundShape());
  
  // The only shape type that we can use as a background is a rectangle.
  Shape shapeRectangle = new Shape(doc, ShapeType.RECTANGLE);
  
  // There are two ways of using this shape as a page background.
  // 1 -  A flat color:
  shapeRectangle.setFillColor(Color.BLUE);
  doc.setBackgroundShape(shapeRectangle);
  
  doc.save(getArtifactsDir() + "DocumentBase.BackgroundShape.FlatColor.docx");
  
  // 2 -  An image:
  shapeRectangle = new Shape(doc, ShapeType.RECTANGLE);
  shapeRectangle.getImageData().setImage(getImageDir() + "Transparent background logo.png");
  
  // Adjust the image's appearance to make it more suitable as a watermark.
  shapeRectangle.getImageData().setContrast(0.2);
  shapeRectangle.getImageData().setBrightness(0.7);
  
  doc.setBackgroundShape(shapeRectangle);
  
  Assert.assertTrue(doc.getBackgroundShape().hasImage());
  
  // Microsoft Word does not support shapes with images as backgrounds,
  // but we can still see these backgrounds in other save formats such as .pdf.
  doc.save(getArtifactsDir() + "DocumentBase.BackgroundShape.Image.pdf");

  See Also:

  ViewOptions.DisplayBackgroundShape, PageColor

• getBuiltInDocumentProperties

  public BuiltInDocumentProperties getBuiltInDocumentProperties()
  

  Returns a collection that represents all the built-in document properties of the document.

  Example:

  Shows how to work with built in document properties.

  Document doc = new Document(getMyDir() + "Properties.docx");
  
  // Some information about the document is stored in member attributes, and can be accessed like this
  System.out.println(MessageFormat.format("Document filename:\n\t \"{0}\"", doc.getOriginalFileName()));
  
  // The majority of metadata, such as author name, file size,
  // word/page counts can be found in the built in properties collection like this
  System.out.println("Built-in Properties:");
  for (DocumentProperty docProperty : doc.getBuiltInDocumentProperties()) {
      System.out.println(docProperty.getName());
      System.out.println(MessageFormat.format("\tType:\t{0}", docProperty.getType()));
  }

• getChildNodes

  public NodeCollection getChildNodes()
  

  Gets all immediate child nodes of this node.

  Note, ChildNodes is equivalent to calling GetChildNodes(NodeType.Any, false) and creates and returns a new collection every time it is accessed.

  If there are no child nodes, this property returns an empty collection.

  Example:

  Shows how to enumerate immediate children of a CompositeNode using the enumerator provided by the ChildNodes collection.

  Document doc = new Document();
  
  Paragraph paragraph = (Paragraph) doc.getChild(NodeType.PARAGRAPH, 0, true);
  paragraph.appendChild(new Run(doc, "Hello world!"));
  paragraph.appendChild(new Run(doc, " Hello again!"));
  
  NodeCollection children = paragraph.getChildNodes();
  
  // Paragraph may contain children of various types such as runs, shapes and so on
  for (Node child : (Iterable<Node>) children)
      if (((child.getNodeType()) == (NodeType.RUN))) {
          Run run = (Run) child;
          System.out.println(run.getText());
      }

• getCompatibilityOptions

  public CompatibilityOptions getCompatibilityOptions()
  

  Provides access to document compatibility options (that is, the user preferences entered on the Compatibility tab of the Options dialog in Word).

• getCompliance

  public int getCompliance()
  

  Gets the OOXML compliance version determined from the loaded document content. Makes sense only for OOXML documents. The value of the property is OoxmlCompliance integer constant.

  If you created a new blank document or load non OOXML document returns the OoxmlCompliance.ECMA_376_2006 value.

  Example:

  Shows how to read a loaded document's Open Office XML compliance version.

  // The compliance version varies between documents created by different versions of Microsoft Word.
  Document doc = new Document(getMyDir() + "Document.doc");
  
  Assert.assertEquals(doc.getCompliance(), OoxmlCompliance.ECMA_376_2006);
  
  doc = new Document(getMyDir() + "Document.docx");
  
  Assert.assertEquals(doc.getCompliance(), OoxmlCompliance.ISO_29500_2008_TRANSITIONAL);

• getCount

  public int getCount()
  

  Gets the number of immediate children of this node.

  Example:

  Shows how to add, update and delete child nodes from a CompositeNode's child collection.

  Document doc = new Document();
  
  // An empty document has one paragraph by default
  Assert.assertEquals(1, doc.getFirstSection().getBody().getParagraphs().getCount());
  
  // A paragraph is a composite node because it can contain runs, which are another type of node
  Paragraph paragraph = doc.getFirstSection().getBody().getFirstParagraph();
  Run paragraphText = new Run(doc, "Initial text. ");
  paragraph.appendChild(paragraphText);
  
  // We will place these 3 children into the main text of our paragraph
  Run run1 = new Run(doc, "Run 1. ");
  Run run2 = new Run(doc, "Run 2. ");
  Run run3 = new Run(doc, "Run 3. ");
  
  // We initialized them but not in our paragraph yet
  Assert.assertEquals("Initial text.", paragraph.getText().trim());
  
  // Insert run2 before initial paragraph text. This will be at the start of the paragraph
  paragraph.insertBefore(run2, paragraphText);
  
  // Insert run3 after initial paragraph text. This will be at the end of the paragraph
  paragraph.insertAfter(run3, paragraphText);
  
  // Insert run1 before every other child node. run2 was the start of the paragraph, now it will be run1
  paragraph.prependChild(run1);
  
  Assert.assertEquals("Run 1. Run 2. Initial text. Run 3.", paragraph.getText().trim());
  Assert.assertEquals(4, paragraph.getChildNodes(NodeType.ANY, true).getCount());
  
  // Access the child node collection and update/delete children
  ((Run) paragraph.getChildNodes(NodeType.RUN, true).get(1)).setText("Updated run 2. ");
  paragraph.getChildNodes(NodeType.RUN, true).remove(paragraphText);
  
  Assert.assertEquals("Run 1. Updated run 2. Run 3.", paragraph.getText().trim());
  Assert.assertEquals(3, paragraph.getChildNodes(NodeType.ANY, true).getCount());

• getCustomDocumentProperties

  public CustomDocumentProperties getCustomDocumentProperties()
  

  Returns a collection that represents all the custom document properties of the document.

  Example:

  Shows how to work with built in document properties.

  Document doc = new Document(getMyDir() + "Properties.docx");
  
  // Some information about the document is stored in member attributes, and can be accessed like this
  System.out.println(MessageFormat.format("Document filename:\n\t \"{0}\"", doc.getOriginalFileName()));
  
  // The majority of metadata, such as author name, file size,
  // word/page counts can be found in the built in properties collection like this
  System.out.println("Built-in Properties:");
  for (DocumentProperty docProperty : doc.getBuiltInDocumentProperties()) {
      System.out.println(docProperty.getName());
      System.out.println(MessageFormat.format("\tType:\t{0}", docProperty.getType()));
  }

• getCustomXmlParts/setCustomXmlParts

  public CustomXmlPartCollection getCustomXmlParts() / public void setCustomXmlParts(CustomXmlPartCollection value)
  

  Gets or sets the collection of Custom XML Data Storage Parts.

  Aspose.Words loads and saves Custom XML Parts into OOXML and DOC documents only.

  This property cannot be null.

  Example:

  Shows how to create structured document tag with a custom XML data.

  Document doc = new Document();
  
  // Construct an XML part that contains data and add it to the document's collection
  // Once the "Developer" tab in Mircosoft Word is enabled,
  // we can find elements from this collection as well as a couple defaults in the "XML Mapping Pane"
  String xmlPartId = UUID.randomUUID().toString();
  String xmlPartContent = "<root><text>Hello, World!</text></root>";
  CustomXmlPart xmlPart = doc.getCustomXmlParts().add(xmlPartId, xmlPartContent);
  
  // The data we entered resides in these variables
  Assert.assertEquals(xmlPart.getData(), xmlPartContent.getBytes());
  Assert.assertEquals(xmlPart.getId(), xmlPartId);
  
  // XML parts can be referenced by collection index or GUID
  Assert.assertEquals(doc.getCustomXmlParts().get(0), xmlPart);
  Assert.assertEquals(doc.getCustomXmlParts().getById(xmlPartId), xmlPart);
  
  // Once the part is created, we can add XML schema associations like this
  xmlPart.getSchemas().add("http://www.w3.org/2001/XMLSchema");
  
  // We can also clone parts and insert them into the collection directly
  CustomXmlPart xmlPartClone = xmlPart.deepClone();
  xmlPartClone.setId(UUID.randomUUID().toString());
  doc.getCustomXmlParts().add(xmlPartClone);
  
  Assert.assertEquals(doc.getCustomXmlParts().getCount(), 2);
  
  // Iterate through collection with an enumerator and print the contents of each part
  Iterator<CustomXmlPart> enumerator = doc.getCustomXmlParts().iterator();
  int index = 0;
  while (enumerator.hasNext()) {
      CustomXmlPart customXmlPart = enumerator.next();
      System.out.println(MessageFormat.format("XML part index {0}, ID: {1}", index, customXmlPart.getId()));
      System.out.println(MessageFormat.format("\tContent: {0}", customXmlPart.getData()));
      index++;
  }
  
  // XML parts can be removed by index
  doc.getCustomXmlParts().removeAt(1);
  
  Assert.assertEquals(doc.getCustomXmlParts().getCount(), 1);
  
  // The XML part collection itself can be cloned also
  CustomXmlPartCollection customXmlParts = doc.getCustomXmlParts().deepClone();
  
  // And all elements can be cleared like this
  customXmlParts.clear();
  
  // Create a StructuredDocumentTag that will display the contents of our part,
  // insert it into the document and save the document
  StructuredDocumentTag sdt = new StructuredDocumentTag(doc, SdtType.PLAIN_TEXT, MarkupLevel.BLOCK);
  sdt.getXmlMapping().setMapping(xmlPart, "/root[1]/text[1]", "");
  
  doc.getFirstSection().getBody().appendChild(sdt);
  
  doc.save(getArtifactsDir() + "StructuredDocumentTag.CustomXml.docx");

  See Also:

  CustomXmlPart

• getDefaultTabStop/setDefaultTabStop

  public double getDefaultTabStop() / public void setDefaultTabStop(double value)
  

  Gets or sets the interval (in points) between the default tab stops.

  Example:

  Shows how to set a custom interval for tab stop positions.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Set tab stops to appear every 72 points (1 inch).
  builder.getDocument().setDefaultTabStop(72.0);
  
  // Each tab character snaps the text after it to the next closest tab stop position.
  builder.writeln("Hello" + ControlChar.TAB + "World!");
  builder.writeln("Hello" + ControlChar.TAB_CHAR + "World!");

  See Also:

  TabStopCollection, TabStop

• getDigitalSignatures

  public DigitalSignatureCollection getDigitalSignatures()
  

  Gets the collection of digital signatures for this document and their validation results.

  This collection contains digital signatures that were loaded from the original document. These digital signatures will not be saved when you save this Document object into a file or stream because saving or converting will produce a document that is different from the original and the original digital signatures will no longer be valid.

  This collection is never null. If the document is not signed, it will contain zero elements.

  Example:

  Shows how to validate and display information about each signature in a document.

  Document doc = new Document(getMyDir() + "Digitally signed.docx");
  
  for (DigitalSignature signature : doc.getDigitalSignatures()) {
      System.out.println("*** Signature Found ***");
      System.out.println("Is valid: " + signature.isValid());
      // This property is available in MS Word documents only
      System.out.println("Reason for signing: " + signature.getComments());
      System.out.println("Signature type: " + signature.getSignatureType());
      System.out.println("Time of signing: " + signature.getSignTime());
      System.out.println("Subject name: " + signature.getSubjectName());
      System.out.println("Issuer name: " + signature.getIssuerName());
      System.out.println();
  }

  Example:

  Shows how to sign documents with X.509 certificates.

  // Verify that a document is not signed.
  Assert.assertFalse(FileFormatUtil.detectFileFormat(getMyDir() + "Document.docx").hasDigitalSignature());
  
  // Create a CertificateHolder object from a PKCS12 file, which we will use to sign the document.
  CertificateHolder certificateHolder = CertificateHolder.create(getMyDir() + "morzal.pfx", "aw", null);
  
  SignOptions signOptions = new SignOptions();
  signOptions.setSignTime(new Date());
  
  // There are two ways of saving a signed copy of a document to the local file system:
  // 1 - Designate a document by a local system filename, and save a signed copy at a location specified by another filename.
  DigitalSignatureUtil.sign(getMyDir() + "Document.docx", getArtifactsDir() + "Document.DigitalSignature.docx", 
      certificateHolder, signOptions);
  
  Assert.assertTrue(FileFormatUtil.detectFileFormat(getArtifactsDir() + "Document.DigitalSignature.docx").hasDigitalSignature());
  
  // 2 - Take a document from a stream, and save a signed copy to another stream.
  InputStream inDoc = new FileInputStream(getMyDir() + "Document.docx");
  try
  {
      OutputStream outDoc = new FileOutputStream(getArtifactsDir() + "Document.DigitalSignature.docx");
      try
      {
          DigitalSignatureUtil.sign(inDoc, outDoc, certificateHolder);
      }
      finally { if (outDoc != null) outDoc.close(); }
  }
  finally { if (inDoc != null) inDoc.close(); }
  
  Assert.assertTrue(FileFormatUtil.detectFileFormat(getArtifactsDir() + "Document.DigitalSignature.docx").hasDigitalSignature());
  
  // Please verify that all of the document's digital signatures are valid, and check their details.
  Document signedDoc = new Document(getArtifactsDir() + "Document.DigitalSignature.docx");
  DigitalSignatureCollection digitalSignatureCollection = signedDoc.getDigitalSignatures();
  
  Assert.assertTrue(digitalSignatureCollection.isValid());
  Assert.assertEquals(1, digitalSignatureCollection.getCount());
  Assert.assertEquals(DigitalSignatureType.XML_DSIG, digitalSignatureCollection.get(0).getSignatureType());
  Assert.assertEquals("CN=Morzal.Me", signedDoc.getDigitalSignatures().get(0).getIssuerName());
  Assert.assertEquals("CN=Morzal.Me", signedDoc.getDigitalSignatures().get(0).getSubjectName());

• getDocument

  public DocumentBase getDocument()
  

• getEndnoteOptions

  public EndnoteOptions getEndnoteOptions()
  

  Provides options that control numbering and positioning of endnotes in this document.

  Example:

  Shows how to insert endnotes, and modify their appearance.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.write("Text 1. ");
  builder.insertFootnote(FootnoteType.ENDNOTE, "Endnote 1");
  builder.write("Text 2. ");
  builder.insertFootnote(FootnoteType.ENDNOTE, "Endnote 2");
  builder.insertBreak(BreakType.PAGE_BREAK);
  builder.write("Text 3. ");
  builder.insertFootnote(FootnoteType.ENDNOTE, "Endnote 3", "Custom reference mark");
  
  doc.getEndnoteOptions().setPosition(EndnotePosition.END_OF_DOCUMENT);
  doc.getEndnoteOptions().setNumberStyle(NumberStyle.UPPERCASE_ROMAN);
  doc.getEndnoteOptions().setRestartRule(FootnoteNumberingRule.CONTINUOUS);
  doc.getEndnoteOptions().setStartNumber(1);
  
  doc.save(getArtifactsDir() + "InlineStory.Endnotes.docx");

• getFieldOptions

  public FieldOptions getFieldOptions()
  

  Gets a FieldOptions object that represents options to control field handling in the document.

• getFirstChild

  public Node getFirstChild()
  

  Gets the first child of the node.

  If there is no first child node, a null is returned.

  Example:

  Shows how to enumerate immediate child nodes of a composite node using NextSibling.

  Document doc = new Document(getMyDir() + "Paragraphs.docx");
  
  // Loop starting from the first child until we reach null
  for (Node node = doc.getFirstSection().getBody().getFirstChild(); node != null; node = node.getNextSibling()) {
      // Output the types of the nodes that we come across
      System.out.println(Node.nodeTypeToString(node.getNodeType()));
  }

  Example:

  Shows how to efficiently visit all direct and indirect children of a composite node.

  public void recurseAllNodes() throws Exception {
      Document doc = new Document(getMyDir() + "Paragraphs.docx");
  
      // Any node that can contain child nodes, such as the document itself, is composite
      Assert.assertTrue(doc.isComposite());
  
      // Invoke the recursive function that will go through and print all the child nodes of a composite node
      traverseAllNodes(doc, 0);
  }
  
  /// <summary>
  /// Recursively traverses a node tree while printing the type of each node with an indent depending on depth as well as the contents of all inline nodes.
  /// </summary>
  @Test(enabled = false)
  public void traverseAllNodes(CompositeNode parentNode, int depth) {
      // Loop through immediate children of a node
      for (Node childNode = parentNode.getFirstChild(); childNode != null; childNode = childNode.getNextSibling()) {
          System.out.println(MessageFormat.format("{0}{1}", String.format("    ", depth), Node.nodeTypeToString(childNode.getNodeType())));
  
          // Recurse into the node if it is a composite node
          if (childNode.isComposite()) {
              System.out.println();
              traverseAllNodes((CompositeNode) childNode, depth + 1);
          } else if (childNode instanceof Inline) {
              System.out.println(" - \"{childNode.GetText().Trim()}\"");
          } else {
              System.out.println();
          }
      }
  }

• getFirstSection

  public Section getFirstSection()
  

  Gets the first section in the document.

  Returns null if there are no sections.

  Example:

  Shows how to replace text in the document footer.

  // Open the template document, containing obsolete copyright information in the footer
  Document doc = new Document(getMyDir() + "Footer.docx");
  
  HeaderFooterCollection headersFooters = doc.getFirstSection().getHeadersFooters();
  HeaderFooter footer = headersFooters.getByHeaderFooterType(HeaderFooterType.FOOTER_PRIMARY);
  
  FindReplaceOptions options = new FindReplaceOptions();
  options.setMatchCase(false);
  options.setFindWholeWordsOnly(false);
  
  int currentYear = new Date().getYear();
  footer.getRange().replace("(C) 2006 Aspose Pty Ltd.", MessageFormat.format("Copyright (C) {0} by Aspose Pty Ltd.", currentYear), options);
  
  doc.save(getArtifactsDir() + "HeaderFooter.ReplaceText.docx");

  Example:

  Shows how to create a new section with a document builder.

  Document doc = new Document();
  
  // A blank document contains one section by default,
  // in order for us to be able to edit it straight away.
  Assert.assertEquals(1, doc.getSections().getCount());
  
  // Use a document builder to add text, and then to create a new section by inserting a section break.
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.writeln("Hello world!");
  builder.insertBreak(BreakType.SECTION_BREAK_NEW_PAGE);
  
  Assert.assertEquals(2, doc.getSections().getCount());
  
  // Each section is a subdivision of the document that has its own page setup settings.
  // We can split up the text in the second section into two columns without affecting the first section in any way.
  doc.getLastSection().getPageSetup().getTextColumns().setCount(2);
  builder.writeln("Column 1.");
  builder.insertBreak(BreakType.COLUMN_BREAK);
  builder.writeln("Column 2.");
  
  Assert.assertEquals(1, doc.getFirstSection().getPageSetup().getTextColumns().getCount());
  Assert.assertEquals(2, doc.getLastSection().getPageSetup().getTextColumns().getCount());
  
  doc.save(getArtifactsDir() + "Section.Create.docx");

  Example:

  Shows how you can enumerate through children of a composite node and detect types of the children nodes.

  // Open a document
  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.write("Section 1");
  builder.moveToHeaderFooter(HeaderFooterType.HEADER_PRIMARY);
  builder.write("Primary header");
  builder.moveToHeaderFooter(HeaderFooterType.FOOTER_PRIMARY);
  builder.write("Primary footer");
  
  // Get the first section in the document
  Section section = doc.getFirstSection();
  
  // A Section is a composite node and therefore can contain child nodes
  // Section can contain only Body and HeaderFooter nodes
  for (Node node : section) {
      // Every node has the NodeType property
      switch (node.getNodeType()) {
          case NodeType.BODY:
              // If the node type is Body, we can cast the node to the Body class
              Body body = (Body) node;
  
              // Write the content of the main story of the section to the console
              System.out.println("*** Body ***");
              System.out.println(body.getText());
              break;
  
          case NodeType.HEADER_FOOTER:
              // If the node type is HeaderFooter, we can cast the node to the HeaderFooter class
              HeaderFooter headerFooter = (HeaderFooter) node;
  
              // Write the content of the header footer to the console
              System.out.println("*** HeaderFooter ***");
              System.out.println(headerFooter.getHeaderFooterType());
              System.out.println(headerFooter.getText());
              break;
  
          default:
              // Other types of nodes never occur inside a Section node
              throw new Exception("Unexpected node type in a section.");
      }
  }

• getFontInfos

  public FontInfoCollection getFontInfos()
  

  Provides access to properties of fonts used in this document.

  This collection of font definitions is loaded as is from the document. Font definitions might be optional, missing or incomplete in some documents.

  Do not rely on this collection to ascertain that a particular font is used in the document. You should only use this collection to get information about fonts that might be used in the document.

  Example:

  Shows how to save a document with embedded TrueType fonts.

  Document doc = new Document(getMyDir() + "Document.docx");
  
  FontInfoCollection fontInfos = doc.getFontInfos();
  fontInfos.setEmbedTrueTypeFonts(true);
  fontInfos.setEmbedSystemFonts(false);
  fontInfos.setSaveSubsetFonts(false);
  
  doc.save(getArtifactsDir() + "Font.FontInfoCollection.docx");

  Example:

  Shows how to print the details of what fonts are present in a document.

  Document doc = new Document(getMyDir() + "Embedded font.docx");
  
  FontInfoCollection fonts = doc.getFontInfos();
  
  int fontIndex = 0;
  // The fonts info extracted from this document does not necessarily mean that the fonts themselves are
  // used in the document. If a font is present but not used then most likely they were referenced at some time
  // and then removed from the Document
  for (FontInfo info : fonts) {
      // Print out some important details about the font
      System.out.println(MessageFormat.format("Font #{0}", fontIndex));
      System.out.println(MessageFormat.format("Name: {0}", info.getName()));
      System.out.println(MessageFormat.format("IsTrueType: {0}", info.isTrueType()));
      fontIndex++;
  }

  See Also:

  FontInfoCollection, FontInfo

• getFontSettings/setFontSettings

  public FontSettings getFontSettings() / public void setFontSettings(FontSettings value)
  

  Gets or sets document font settings.

  This property allows to specify font settings per document. If set to null, default static font settings FontSettings.DefaultInstance will be used.

  The default value is null.

  Example:

  Shows how to define alternative fonts if original does not exist.

  FontSettings fontSettings = new FontSettings();
  fontSettings.getSubstitutionSettings().getTableSubstitution().addSubstitutes("Times New Roman", "Slab", "Arvo");

• getFootnoteOptions

  public FootnoteOptions getFootnoteOptions()
  

  Provides options that control numbering and positioning of footnotes in this document.

• getGlossaryDocument/setGlossaryDocument

  public GlossaryDocument getGlossaryDocument() / public void setGlossaryDocument(GlossaryDocument value)
  

  Gets or sets the glossary document within this document or template. A glossary document is a storage for AutoText, AutoCorrect and Building Block entries defined in a document.

  This property returns null if the document does not have a glossary document.

  You can add a glossary document to a document by creating a GlossaryDocument object and assigning to this property.

  Example:

  Shows how to add a custom building block to a document.

  public void createAndInsert() throws Exception
  {
      // A document's glossary document stores building blocks.
      Document doc = new Document();
      GlossaryDocument glossaryDoc = new GlossaryDocument();
      doc.setGlossaryDocument(glossaryDoc);
  
      // Create a building block, name it, and then add it to the glossary document.
      BuildingBlock block = new BuildingBlock(glossaryDoc);
      block.setName("Custom Block");
  
      glossaryDoc.appendChild(block);
  
      // All new building block GUIDs have the same zero value by default, and we can give them a new unique value.
      Assert.assertEquals(block.getGuid().toString(), "00000000-0000-0000-0000-000000000000");
  
      block.setGuid(UUID.randomUUID());
  
      // The following attributes categorize building blocks
      // in the menu found via Insert -> Quick Parts -> Building Blocks Organizer in Microsoft Word.
      Assert.assertEquals(block.getCategory(), "(Empty Category)");
      Assert.assertEquals(block.getType(), BuildingBlockType.NONE);
      Assert.assertEquals(block.getGallery(), BuildingBlockGallery.ALL);
      Assert.assertEquals(block.getBehavior(), BuildingBlockBehavior.CONTENT);
  
      // Before we can add this building block to our document, we will need to give it some contents.
      // We will do that and set a category, gallery, and behavior with a document visitor.
      BuildingBlockVisitor visitor = new BuildingBlockVisitor(glossaryDoc);
      block.accept(visitor);
  
      // We can access the block that we just made from the glossary document.
      BuildingBlock customBlock = glossaryDoc.getBuildingBlock(BuildingBlockGallery.QUICK_PARTS,
              "My custom building blocks", "Custom Block");
  
      // The block itself is a section that contains the text.
      Assert.assertEquals(MessageFormat.format("Text inside {0}\f", customBlock.getName()), customBlock.getFirstSection().getBody().getFirstParagraph().getText());
      Assert.assertEquals(customBlock.getFirstSection(), customBlock.getLastSection());
  
      // Now, we can insert it into the document as a new section.
      doc.appendChild(doc.importNode(customBlock.getFirstSection(), true));
  
      // We can also find it in Microsoft Word's Building Blocks Organizer and place it manually.
      doc.save(getArtifactsDir() + "BuildingBlocks.CreateAndInsert.dotx");
  }
  
  /// <summary>
  /// Sets up a visited building block to be inserted into the document as a quick part and adds text to its contents.
  /// </summary>
  public static class BuildingBlockVisitor extends DocumentVisitor {
      public BuildingBlockVisitor(final GlossaryDocument ownerGlossaryDoc) {
          mBuilder = new StringBuilder();
          mGlossaryDoc = ownerGlossaryDoc;
      }
  
      public int visitBuildingBlockStart(final BuildingBlock block) {
          // Configure the building block as a quick part, and add attributes used by Building Blocks Organizer.
          block.setBehavior(BuildingBlockBehavior.PARAGRAPH);
          block.setCategory("My custom building blocks");
          block.setDescription("Using this block in the Quick Parts section of word will place its contents at the cursor.");
          block.setGallery(BuildingBlockGallery.QUICK_PARTS);
  
          // Add a section with text.
          // Inserting the block into the document will append this section with its child nodes at the location.
          Section section = new Section(mGlossaryDoc);
          block.appendChild(section);
          block.getFirstSection().ensureMinimum();
  
          Run run = new Run(mGlossaryDoc, "Text inside " + block.getName());
          block.getFirstSection().getBody().getFirstParagraph().appendChild(run);
  
          return VisitorAction.CONTINUE;
      }
  
      public int visitBuildingBlockEnd(final BuildingBlock block) {
          mBuilder.append("Visited " + block.getName() + "\r\n");
          return VisitorAction.CONTINUE;
      }
  
      private StringBuilder mBuilder;
      private GlossaryDocument mGlossaryDoc;
  }

  See Also:

  GlossaryDocument

• hasChildNodes

  public boolean hasChildNodes()
  

  Returns true if this node has any child nodes.

  Example:

  Shows how to combine the rows from two tables into one.

  // Load the document
  Document doc = new Document(getMyDir() + "Tables.docx");
  
  // Get the first and second table in the document
  // The rows from the second table will be appended to the end of the first table
  Table firstTable = (Table) doc.getChild(NodeType.TABLE, 0, true);
  Table secondTable = (Table) doc.getChild(NodeType.TABLE, 1, true);
  
  // Append all rows from the current table to the next
  // Due to the design of tables even tables with different cell count and widths can be joined into one table
  while (secondTable.hasChildNodes())
      firstTable.getRows().add(secondTable.getFirstRow());
  
  // Remove the empty table container
  secondTable.remove();
  
  doc.save(getArtifactsDir() + "Table.CombineTables.docx");

• hasMacros

  public boolean hasMacros()
  

  Returns true if the document has a VBA project (macros).

  Example:

  Shows how to use MACROBUTTON fields that enable us to run macros by clicking.

  // Open a document that contains macros
  Document doc = new Document(getMyDir() + "Macro.docm");
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  Assert.assertTrue(doc.hasMacros());
  
  // Insert a MACROBUTTON field and reference by name a macro that exists within the input document
  FieldMacroButton field = (FieldMacroButton) builder.insertField(FieldType.FIELD_MACRO_BUTTON, true);
  field.setMacroName("MyMacro");
  field.setDisplayText("Double click to run macro: " + field.getMacroName());
  
  Assert.assertEquals(" MACROBUTTON  MyMacro Double click to run macro: MyMacro", field.getFieldCode());
  
  // Reference "ViewZoom200", a macro that was shipped with Microsoft Word, found under "Word commands"
  // If our document has a macro of the same name as one from another source, the field will select ours to run
  builder.insertParagraph();
  field = (FieldMacroButton) builder.insertField(FieldType.FIELD_MACRO_BUTTON, true);
  field.setMacroName("ViewZoom200");
  field.setDisplayText("Run " + field.getMacroName());
  
  Assert.assertEquals(field.getFieldCode(), " MACROBUTTON  ViewZoom200 Run ViewZoom200");
  
  // Save the document as a macro-enabled document type
  doc.save(getArtifactsDir() + "Field.MACROBUTTON.docm");

  See Also:

  removeMacros()

• hasRevisions

  public boolean hasRevisions()
  

  Returns true if the document has any tracked changes.

  This property is a shortcut for comparing RevisionCollection.Count to zero.

• getHyphenationOptions

  public HyphenationOptions getHyphenationOptions()
  

  Provides access to document hyphenation options.

  Example:

  Shows how to configure automatic hyphenation.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.getFont().setSize(24.0);
  builder.writeln("Lorem ipsum dolor sit amet, consectetur adipiscing elit, " +
          "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.");
  
  doc.getHyphenationOptions().setAutoHyphenation(true);
  doc.getHyphenationOptions().setConsecutiveHyphenLimit(2);
  doc.getHyphenationOptions().setHyphenationZone(720);
  doc.getHyphenationOptions().setHyphenateCaps(true);
  
  doc.save(getArtifactsDir() + "Document.HyphenationOptions.docx");

• isComposite

  public boolean isComposite()
  

  Returns true as this node can have child nodes.

  Example:

  Shows how to efficiently visit all direct and indirect children of a composite node.

  public void recurseAllNodes() throws Exception {
      Document doc = new Document(getMyDir() + "Paragraphs.docx");
  
      // Any node that can contain child nodes, such as the document itself, is composite
      Assert.assertTrue(doc.isComposite());
  
      // Invoke the recursive function that will go through and print all the child nodes of a composite node
      traverseAllNodes(doc, 0);
  }
  
  /// <summary>
  /// Recursively traverses a node tree while printing the type of each node with an indent depending on depth as well as the contents of all inline nodes.
  /// </summary>
  @Test(enabled = false)
  public void traverseAllNodes(CompositeNode parentNode, int depth) {
      // Loop through immediate children of a node
      for (Node childNode = parentNode.getFirstChild(); childNode != null; childNode = childNode.getNextSibling()) {
          System.out.println(MessageFormat.format("{0}{1}", String.format("    ", depth), Node.nodeTypeToString(childNode.getNodeType())));
  
          // Recurse into the node if it is a composite node
          if (childNode.isComposite()) {
              System.out.println();
              traverseAllNodes((CompositeNode) childNode, depth + 1);
          } else if (childNode instanceof Inline) {
              System.out.println(" - \"{childNode.GetText().Trim()}\"");
          } else {
              System.out.println();
          }
      }
  }

• getLastChild

  public Node getLastChild()
  

  Gets the last child of the node.

  If there is no last child node, a null is returned.

  Example:

  Shows how to use of methods of Node and CompositeNode to remove a section before the last section in the document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Create a second section by inserting a section break and add text to both sections
  builder.writeln("Section 1 text.");
  builder.insertBreak(BreakType.SECTION_BREAK_CONTINUOUS);
  builder.writeln("Section 2 text.");
  
  // Both sections are siblings of each other
  Section lastSection = (Section) doc.getLastChild();
  Section firstSection = (Section) lastSection.getPreviousSibling();
  
  // Remove a section based on its sibling relationship with another section
  if (lastSection.getPreviousSibling() != null)
      doc.removeChild(firstSection);
  
  // The section we removed was the first one, leaving the document with only the second
  Assert.assertEquals("Section 2 text.", doc.getText().trim());

• getLastSection

  public Section getLastSection()
  

  Gets the last section in the document.

  Returns null if there are no sections.

  Example:

  Shows how to create a new section with a document builder.

  Document doc = new Document();
  
  // A blank document contains one section by default,
  // in order for us to be able to edit it straight away.
  Assert.assertEquals(1, doc.getSections().getCount());
  
  // Use a document builder to add text, and then to create a new section by inserting a section break.
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.writeln("Hello world!");
  builder.insertBreak(BreakType.SECTION_BREAK_NEW_PAGE);
  
  Assert.assertEquals(2, doc.getSections().getCount());
  
  // Each section is a subdivision of the document that has its own page setup settings.
  // We can split up the text in the second section into two columns without affecting the first section in any way.
  doc.getLastSection().getPageSetup().getTextColumns().setCount(2);
  builder.writeln("Column 1.");
  builder.insertBreak(BreakType.COLUMN_BREAK);
  builder.writeln("Column 2.");
  
  Assert.assertEquals(1, doc.getFirstSection().getPageSetup().getTextColumns().getCount());
  Assert.assertEquals(2, doc.getLastSection().getPageSetup().getTextColumns().getCount());
  
  doc.save(getArtifactsDir() + "Section.Create.docx");

• getLayoutOptions

  public LayoutOptions getLayoutOptions()
  

  Gets a LayoutOptions object that represents options to control the layout process of this document.

  Example:

  Shows how to hide text in a rendered output document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Insert hidden text, then specify whether we wish to omit it from a rendered document.
  builder.writeln("This text is not hidden.");
  builder.getFont().setHidden(true);
  builder.writeln("This text is hidden.");
  
  doc.getLayoutOptions().setShowHiddenText(showHiddenText);
  
  doc.save(getArtifactsDir() + "Document.LayoutOptionsHiddenText.pdf");

  Example:

  Shows how to show paragraph marks in a rendered output document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Add some paragraphs, then enable paragraph marks to show the ends of paragraphs
  // with a pilcrow (¶) symbol when we render the document.
  builder.writeln("Hello world!");
  builder.writeln("Hello again!");
  
  doc.getLayoutOptions().setShowParagraphMarks(showParagraphMarks);
  
  doc.save(getArtifactsDir() + "Document.LayoutOptionsParagraphMarks.pdf");

  Example:

  Shows how to alter the appearance of revisions in a rendered output document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Insert a revision, then change the color of all revisions to green,
  // and also remove the bar that appears to the left of every revised line.
  builder.writeln("This is not a revision.");
  doc.startTrackRevisions("John Doe", new Date());
  builder.writeln("This is a revision.");
  doc.stopTrackRevisions();
  builder.writeln("This is not a revision.");
  
  doc.getLayoutOptions().getRevisionOptions().setInsertedTextColor(RevisionColor.BRIGHT_GREEN);
  doc.getLayoutOptions().getRevisionOptions().setShowRevisionBars(false);
  
  doc.save(getArtifactsDir() + "Document.LayoutOptionsRevisions.pdf");

• getLists

  public ListCollection getLists()
  

  Provides access to the list formatting used in the document.

  For more information see the description of the ListCollection class.

  Example:

  Shows how to specify list level number when building a list using DocumentBuilder.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Create a numbered list based on one of the Microsoft Word list templates and
  // apply it to the current paragraph in the document builder
  builder.getListFormat().setList(doc.getLists().add(ListTemplate.NUMBER_ARABIC_DOT));
  
  // Insert text at each of the 9 indent levels
  for (int i = 0; i < 9; i++) {
      builder.getListFormat().setListLevelNumber(i);
      builder.writeln("Level " + i);
  }
  
  // Create a bulleted list based on one of the Microsoft Word list templates
  // and apply it to the current paragraph in the document builder
  builder.getListFormat().setList(doc.getLists().add(ListTemplate.BULLET_DIAMONDS));
  
  for (int i = 0; i < 9; i++) {
      builder.getListFormat().setListLevelNumber(i);
      builder.writeln("Level " + i);
  }
  
  // This is a way to stop list formatting
  builder.getListFormat().setList(null);
  
  doc.save(getArtifactsDir() + "Lists.SpecifyListLevel.docx");

  See Also:

  ListCollection, List, ListFormat

• getMailMerge

  public MailMerge getMailMerge()
  

  Returns a MailMerge object that represents the mail merge functionality for the document.

  Example:

  Executes mail merge from data stored in a ResultSet.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.insertField(" MERGEFIELD CustomerName ");
  builder.insertParagraph();
  builder.insertField(" MERGEFIELD Address ");
  
  // This example creates a table, but you would normally load table from a database
  DataTable table = new DataTable("Test");
  table.getColumns().add("CustomerName");
  table.getColumns().add("Address");
  table.getRows().add(new Object[]{"Thomas Hardy", "120 Hanover Sq., London"});
  table.getRows().add(new Object[]{"Paolo Accorti", "Via Monte Bianco 34, Torino"});
  
  // Field values from the table are inserted into the mail merge fields found in the document
  doc.getMailMerge().execute(table);
  
  doc.save(getArtifactsDir() + "MailMerge.ExecuteDataTable.docx");
  
  // Create a copy of our document to perform another mail merge
  doc = new Document();
  builder = new DocumentBuilder(doc);
  builder.insertField(" MERGEFIELD CustomerName ");
  builder.insertParagraph();
  builder.insertField(" MERGEFIELD Address ");
  
  // We can also source values for a mail merge from a single row in the table
  doc.getMailMerge().execute(table.getRows().get(1));
  
  doc.save(getArtifactsDir() + "MailMerge.ExecuteDataTable.OneRow.docx");

• getMailMergeSettings/setMailMergeSettings

  public MailMergeSettings getMailMergeSettings() / public void setMailMergeSettings(MailMergeSettings value)
  

  Gets or sets the object that contains all of the mail merge information for a document.

  You can use this object to specify a mail merge data source for a document and this information (along with the available data fields) will appear in Microsoft Word when the user opens this document. Or you can use this object to query mail merge settings that the user has specified in Microsoft Word for this document.

  This object is never null.

• getNextSibling

  public Node getNextSibling()
  

  Gets the node immediately following this node.

  If there is no next node, a null is returned.

  Example:

  Shows how to enumerate immediate child nodes of a composite node using NextSibling.

  Document doc = new Document(getMyDir() + "Paragraphs.docx");
  
  // Loop starting from the first child until we reach null
  for (Node node = doc.getFirstSection().getBody().getFirstChild(); node != null; node = node.getNextSibling()) {
      // Output the types of the nodes that we come across
      System.out.println(Node.nodeTypeToString(node.getNodeType()));
  }

  Example:

  Shows how to efficiently visit all direct and indirect children of a composite node.

  public void recurseAllNodes() throws Exception {
      Document doc = new Document(getMyDir() + "Paragraphs.docx");
  
      // Any node that can contain child nodes, such as the document itself, is composite
      Assert.assertTrue(doc.isComposite());
  
      // Invoke the recursive function that will go through and print all the child nodes of a composite node
      traverseAllNodes(doc, 0);
  }
  
  /// <summary>
  /// Recursively traverses a node tree while printing the type of each node with an indent depending on depth as well as the contents of all inline nodes.
  /// </summary>
  @Test(enabled = false)
  public void traverseAllNodes(CompositeNode parentNode, int depth) {
      // Loop through immediate children of a node
      for (Node childNode = parentNode.getFirstChild(); childNode != null; childNode = childNode.getNextSibling()) {
          System.out.println(MessageFormat.format("{0}{1}", String.format("    ", depth), Node.nodeTypeToString(childNode.getNodeType())));
  
          // Recurse into the node if it is a composite node
          if (childNode.isComposite()) {
              System.out.println();
              traverseAllNodes((CompositeNode) childNode, depth + 1);
          } else if (childNode instanceof Inline) {
              System.out.println(" - \"{childNode.GetText().Trim()}\"");
          } else {
              System.out.println();
          }
      }
  }

• getNodeChangingCallback/setNodeChangingCallback

  public INodeChangingCallback getNodeChangingCallback() / public void setNodeChangingCallback(INodeChangingCallback value)
  

  Called when a node is inserted or removed in the document.

  Example:

  Shows how customize node changing with a callback.

  public void fontChangeViaCallback() throws Exception {
      Document doc = new Document();
      DocumentBuilder builder = new DocumentBuilder(doc);
  
      // Set the node changing callback to custom implementation,
      // then add/remove nodes to get it to generate a log.
      HandleNodeChangingFontChanger callback = new HandleNodeChangingFontChanger();
      doc.setNodeChangingCallback(callback);
  
      builder.writeln("Hello world!");
      builder.writeln("Hello again!");
      builder.insertField(" HYPERLINK \"https://www.google.com/\" ");
      builder.insertShape(ShapeType.RECTANGLE, 300.0, 300.0);
  
      doc.getRange().getFields().get(0).remove();
  
      System.out.println(callback.getLog());
  }
  
  /// <summary>
  /// Logs the date and time of each node insertion and removal,
  /// and also set a custom font name/size for the text contents of Run nodes.
  /// </summary>
  public static class HandleNodeChangingFontChanger implements INodeChangingCallback
  {
      public void nodeInserted(NodeChangingArgs args)
      {
          mLog.append(MessageFormat.format("\tType:\t{0}", args.getNode().getNodeType()));
          mLog.append(MessageFormat.format("\tHash:\t{0}", args.getNode().hashCode()));
  
          if (args.getNode().getNodeType() == NodeType.RUN)
          {
              Font font = ((Run) args.getNode()).getFont();
              mLog.append(MessageFormat.format("\tFont:\tChanged from \"{0}\" {1}pt", font.getName(), font.getSize()));
  
              font.setSize(24.0);
              font.setName("Arial");
  
              mLog.append(MessageFormat.format(" to \"{0}\" {1}pt", font.getName(), font.getSize()));
              mLog.append(MessageFormat.format("\tContents:\n\t\t\"{0}\"", args.getNode().getText()));
          }
      }
  
      public void nodeInserting(NodeChangingArgs args)
      {
          mLog.append(MessageFormat.format("\n{0}\tNode insertion:", new Date()));
      }
  
      public void nodeRemoved(NodeChangingArgs args)
      {
          mLog.append(MessageFormat.format("\tType:\t{0}", args.getNode().getNodeType()));
          mLog.append(MessageFormat.format("\tHash code:\t{0}", args.getNode().hashCode()));
      }
  
      public void nodeRemoving(NodeChangingArgs args)
      {
          mLog.append(MessageFormat.format("\n{0}\tNode removal:", new Date()));
      }
  
      public String getLog()
      {
          return mLog.toString();
      }
  
      private StringBuilder mLog = new StringBuilder();
  }

• getNodeType

  public int getNodeType()
  

  Returns NodeType.Document. The value of the property is NodeType integer constant.

  Example:

  Shows how to efficiently visit all direct and indirect children of a composite node.

  public void recurseAllNodes() throws Exception {
      Document doc = new Document(getMyDir() + "Paragraphs.docx");
  
      // Any node that can contain child nodes, such as the document itself, is composite
      Assert.assertTrue(doc.isComposite());
  
      // Invoke the recursive function that will go through and print all the child nodes of a composite node
      traverseAllNodes(doc, 0);
  }
  
  /// <summary>
  /// Recursively traverses a node tree while printing the type of each node with an indent depending on depth as well as the contents of all inline nodes.
  /// </summary>
  @Test(enabled = false)
  public void traverseAllNodes(CompositeNode parentNode, int depth) {
      // Loop through immediate children of a node
      for (Node childNode = parentNode.getFirstChild(); childNode != null; childNode = childNode.getNextSibling()) {
          System.out.println(MessageFormat.format("{0}{1}", String.format("    ", depth), Node.nodeTypeToString(childNode.getNodeType())));
  
          // Recurse into the node if it is a composite node
          if (childNode.isComposite()) {
              System.out.println();
              traverseAllNodes((CompositeNode) childNode, depth + 1);
          } else if (childNode instanceof Inline) {
              System.out.println(" - \"{childNode.GetText().Trim()}\"");
          } else {
              System.out.println();
          }
      }
  }

• getOriginalFileName

  public java.lang.String getOriginalFileName()
  

  Gets the original file name of the document.

  Returns null if the document was loaded from a stream or created blank.

  Example:

  Shows how to retrieve details of a document's load operation.

  Document doc = new Document(getMyDir() + "Document.docx");
  
  Assert.assertEquals(getMyDir() + "Document.docx", doc.getOriginalFileName());
  Assert.assertEquals(LoadFormat.DOCX, doc.getOriginalLoadFormat());

  Example:

  Shows how to use the FileFormatUtil methods to detect the format of a document without any extension and save it with the correct file extension.

  // Load the document without a file extension into a stream and use the DetectFileFormat method to detect it's format
  // These are both times where you might need extract the file format as it's not visible
  // The file format of this document is actually ".doc"
  FileInputStream docStream = new FileInputStream(getMyDir() + "Word document with missing file extension");
  FileFormatInfo info = FileFormatUtil.detectFileFormat(docStream);
  
  // Retrieve the LoadFormat of the document
  int loadFormat = info.getLoadFormat();
  
  // Let's show the different methods of converting LoadFormat enumerations to SaveFormat enumerations
  //
  // Method #1
  // Convert the LoadFormat to a String first for working with. The String will include the leading dot in front of the extension
  String fileExtension = FileFormatUtil.loadFormatToExtension(loadFormat);
  // Now convert this extension into the corresponding SaveFormat enumeration
  int saveFormat = FileFormatUtil.extensionToSaveFormat(fileExtension);
  
  // Method #2
  // Convert the LoadFormat enumeration directly to the SaveFormat enumeration
  saveFormat = FileFormatUtil.loadFormatToSaveFormat(loadFormat);
  
  // Load a document from the stream.
  Document doc = new Document(docStream);
  
  // Save the document with the original file name, " Out" and the document's file extension
  doc.save(getArtifactsDir() + "File.SaveToDetectedFileFormat" + FileFormatUtil.saveFormatToExtension(saveFormat));

• getOriginalLoadFormat

  public int getOriginalLoadFormat()
  

  Gets the format of the original document that was loaded into this object. The value of the property is LoadFormat integer constant.

  If you created a new blank document, returns the LoadFormat.DOC value.

  Example:

  Shows how to retrieve details of a document's load operation.

  Document doc = new Document(getMyDir() + "Document.docx");
  
  Assert.assertEquals(getMyDir() + "Document.docx", doc.getOriginalFileName());
  Assert.assertEquals(LoadFormat.DOCX, doc.getOriginalLoadFormat());

• getPackageCustomParts/setPackageCustomParts

  public CustomPartCollection getPackageCustomParts() / public void setPackageCustomParts(CustomPartCollection value)
  

  Gets or sets the collection of custom parts (arbitrary content) that are linked to the OOXML package using "unknown relationships".

  Do not confuse these custom parts with Custom XML Data. If you need to access Custom XML parts, use the CustomXmlParts property.

  This collection contains OOXML parts whose parent is the OOXML package and they targets are of an "unknown relationship". For more information see CustomPart.

  Aspose.Words loads and saves custom parts into OOXML documents only.

  This property cannot be null.

  Example:

  Shows how to access a document's arbitrary custom parts collection.

  Document doc = new Document(getMyDir() + "Custom parts OOXML package.docx");
  
  Assert.assertEquals(2, doc.getPackageCustomParts().getCount());
  
  // Clone the second part, then add the clone to the collection.
  CustomPart clonedPart = doc.getPackageCustomParts().get(1).deepClone();
  doc.getPackageCustomParts().add(clonedPart);
  
  Assert.assertEquals(3, doc.getPackageCustomParts().getCount());
  
  // Enumerate over the collection and print every part.
  Iterator<CustomPart> enumerator = doc.getPackageCustomParts().iterator();
  
  int index = 0;
  while (enumerator.hasNext()) {
      CustomPart customPart = (CustomPart) enumerator.next();
      System.out.println(MessageFormat.format("Part index {0}:", index));
      System.out.println(MessageFormat.format("\tName: {0}", customPart.getName()));
      System.out.println(MessageFormat.format("\tContentType: {0}", customPart.getContentType()));
      System.out.println(MessageFormat.format("\tRelationshipType: {0}", customPart.getRelationshipType()));
      if (customPart.isExternal()) {
          System.out.println("\tSourced from outside the document");
      } else {
          System.out.println(MessageFormat.format("\tSourced from within the document, length: {0} bytes", customPart.getData().length));
      }
      index++;
  }
  
  // We can remove elements from this collection individually, or all at once.
  doc.getPackageCustomParts().removeAt(2);
  
  Assert.assertEquals(2, doc.getPackageCustomParts().getCount());
  
  doc.getPackageCustomParts().clear();
  
  Assert.assertEquals(0, doc.getPackageCustomParts().getCount());

  See Also:

  CustomPart

• getPageColor/setPageColor

  public java.awt.Color getPageColor() / public void setPageColor(java.awt.Color value)
  

  Gets or sets the page color of the document. This property is a simpler version of BackgroundShape.

  This property provides a simple way to specify a solid page color for the document. Setting this property creates and sets an appropriate BackgroundShape.

  If the page color is not set (e.g. there is no background shape in the document) returns a zero color.

  Example:

  Shows how to set the background color for all pages of a document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.writeln("Hello world!");
  
  doc.setPageColor(Color.lightGray);
  
  doc.save(getArtifactsDir() + "DocumentBase.SetPageColor.docx");

  See Also:

  BackgroundShape

• getPageCount

  public int getPageCount()
  

  Gets the number of pages in the document as calculated by the most recent page layout operation.

  Example:

  Shows how to count the number of pages in the document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.write("Page 1");
  builder.insertBreak(BreakType.PAGE_BREAK);
  builder.write("Page 2");
  builder.insertBreak(BreakType.PAGE_BREAK);
  builder.write("Page 3");
  
  // Verify the expected page count of the document.
  Assert.assertEquals(3, doc.getPageCount());
  
  // Getting the PageCount property invoked the document's page layout to calculate the value.
  // This operation will not need to be re-done when rendering the document to a fixed-page save format,
  // such as .pdf. So you can save some time, especially with more complex documents.
  doc.save(getArtifactsDir() + "Document.GetPageCount.pdf");

  See Also:

  updatePageLayout()

• getParentNode

  public CompositeNode getParentNode()
  

  Gets the immediate parent of this node.

  If a node has just been created and not yet added to the tree, or if it has been removed from the tree, the parent is null.

  Example:

  Shows how to access the parent node.

  Document doc = new Document();
  
  // Get the document's first paragraph and append a child node to it in the form of a run with text
  Paragraph para = doc.getFirstSection().getBody().getFirstParagraph();
  
  // When inserting a new node, the document that the node will belong to must be provided as an argument
  Run run = new Run(doc, "Hello world!");
  para.appendChild(run);
  
  // The node lineage can be traced back to the document itself
  Assert.assertEquals(para, run.getParentNode());
  Assert.assertEquals(doc.getFirstSection().getBody(), para.getParentNode());
  Assert.assertEquals(doc.getFirstSection(), doc.getFirstSection().getBody().getParentNode());
  Assert.assertEquals(doc, doc.getFirstSection().getParentNode());

  Example:

  Shows how to create a node and set its owning document.

  // Open a file from disk
  Document doc = new Document();
  
  // Creating a new node of any type requires a document passed into the constructor
  Paragraph para = new Paragraph(doc);
  
  // The new paragraph node does not yet have a parent
  System.out.println("Paragraph has no parent node: " + (para.getParentNode() == null));
  
  // But the paragraph node knows its document
  System.out.println("Both nodes' documents are the same: " + (para.getDocument() == doc));
  
  // The fact that a node always belongs to a document allows us to access and modify 
  // properties that reference the document-wide data such as styles or lists
  para.getParagraphFormat().setStyleName("Heading 1");
  
  // Now add the paragraph to the main text of the first section
  doc.getFirstSection().getBody().appendChild(para);
  
  // The paragraph node is now a child of the Body node
  System.out.println("Paragraph has a parent node: " + (para.getParentNode() != null));

• getPreviousSibling

  public Node getPreviousSibling()
  

  Gets the node immediately preceding this node.

  If there is no preceding node, a null is returned.

  Example:

  Shows how to use of methods of Node and CompositeNode to remove a section before the last section in the document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Create a second section by inserting a section break and add text to both sections
  builder.writeln("Section 1 text.");
  builder.insertBreak(BreakType.SECTION_BREAK_CONTINUOUS);
  builder.writeln("Section 2 text.");
  
  // Both sections are siblings of each other
  Section lastSection = (Section) doc.getLastChild();
  Section firstSection = (Section) lastSection.getPreviousSibling();
  
  // Remove a section based on its sibling relationship with another section
  if (lastSection.getPreviousSibling() != null)
      doc.removeChild(firstSection);
  
  // The section we removed was the first one, leaving the document with only the second
  Assert.assertEquals("Section 2 text.", doc.getText().trim());

• getProtectionType

  public int getProtectionType()
  

  Gets the currently active document protection type. The value of the property is ProtectionType integer constant.

  This property allows to retrieve the currently set document protection type. To change the document protection type use the protect(int,java.lang.String) and unprotect() methods.

  When a document is protected, the user can make only limited changes, such as adding annotations, making revisions, or completing a form.

  Note that document protection is different from write protection. Write protection is specified using the WriteProtection

  Example:

  Shows how to protect and unprotect a document.

  Document doc = new Document();
  doc.protect(ProtectionType.READ_ONLY, "password");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, doc.getProtectionType());
  
  // If we open this document with Microsoft Word intending to edit it,
  // we will need to apply the password to get through the protection.
  doc.save(getArtifactsDir() + "Document.Protect.docx");
  
  // Note that the protection only applies to Microsoft Word users opening our document.
  // We have not encrypted the document in any way, and we do not need the password to open and edit it programmatically.
  Document protectedDoc = new Document(getArtifactsDir() + "Document.Protect.docx");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, protectedDoc.getProtectionType());
  
  DocumentBuilder builder = new DocumentBuilder(protectedDoc);
  builder.writeln("Text added to a protected document.");
  
  // There are two ways of removing protection from a document.
  // 1 - With no password:
  doc.unprotect();
  
  Assert.assertEquals(ProtectionType.NO_PROTECTION, doc.getProtectionType());
  
  doc.protect(ProtectionType.READ_ONLY, "NewPassword");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, doc.getProtectionType());
  
  doc.unprotect("WrongPassword");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, doc.getProtectionType());
  
  // 2 - With the correct password:
  doc.unprotect("NewPassword");
  
  Assert.assertEquals(ProtectionType.NO_PROTECTION, doc.getProtectionType());

  See Also:

  protect(int,java.lang.String), unprotect(), WriteProtection

• getRange

  public Range getRange()
  

  Returns a Range object that represents the portion of a document that is contained in this node.

  Example:

  Shows how to delete all characters of a range.

  // Insert two sections into a blank document
  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.write("Section 1. ");
  builder.insertBreak(BreakType.SECTION_BREAK_CONTINUOUS);
  builder.write("Section 2.");
  
  // Verify the whole text of the document
  Assert.assertEquals("Section 1. \fSection 2.", doc.getText().trim());
  
  // Delete the first section from the document
  doc.getSections().get(0).getRange().delete();
  
  // Check the first section was deleted by looking at the text of the whole document again
  Assert.assertEquals("Section 2.", doc.getText().trim());

• getRemovePersonalInformation/setRemovePersonalInformation

  public boolean getRemovePersonalInformation() / public void setRemovePersonalInformation(boolean value)
  

  Gets or sets a flag indicating that Microsoft Word will remove all user information from comments, revisions and document properties upon saving the document.

  Example:

  Shows how to enable the removal of personal information during a manual save.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Insert some content with personal information.
  doc.getBuiltInDocumentProperties().setAuthor("John Doe");
  doc.getBuiltInDocumentProperties().setCompany("Placeholder Inc.");
  
  doc.startTrackRevisions(doc.getBuiltInDocumentProperties().getAuthor(), new Date());
  builder.write("Hello world!");
  doc.stopTrackRevisions();
  
  // This flag is equivalent to File -> Options -> Trust Center -> Trust Center Settings... ->
  // Privacy Options -> "Remove personal information from file properties on save" in Microsoft Word.
  doc.setRemovePersonalInformation(saveWithoutPersonalInfo);
  
  // This option will not take effect during a save operation made using Aspose.Words.
  // Personal data will be removed from our document with the flag set when we save it manually using Microsoft Word.
  doc.save(getArtifactsDir() + "Document.RemovePersonalInformation.docx");
  doc = new Document(getArtifactsDir() + "Document.RemovePersonalInformation.docx");
  
  Assert.assertEquals(saveWithoutPersonalInfo, doc.getRemovePersonalInformation());
  Assert.assertEquals("John Doe", doc.getBuiltInDocumentProperties().getAuthor());
  Assert.assertEquals("Placeholder Inc.", doc.getBuiltInDocumentProperties().getCompany());
  Assert.assertEquals("John Doe", doc.getRevisions().get(0).getAuthor());

• getResourceLoadingCallback/setResourceLoadingCallback

  public IResourceLoadingCallback getResourceLoadingCallback() / public void setResourceLoadingCallback(IResourceLoadingCallback value)
  

  Allows to control how external resources are loaded.

  Example:

  Shows how to customize the process of loading external resources into a document.

  public void resourceLoadingCallback() throws Exception
  {
      Document doc = new Document();
      doc.setResourceLoadingCallback(new ImageNameHandler());
  
      DocumentBuilder builder = new DocumentBuilder(doc);
  
      // Images usually are inserted using a URI, or a byte array.
      // Every instance of a resource load will call our callback's ResourceLoading method.
      builder.insertImage("Google logo");
      builder.insertImage("Aspose logo");
      builder.insertImage("Watermark");
  
      Assert.assertEquals(3, doc.getChildNodes(NodeType.SHAPE, true).getCount());
  
      doc.save(getArtifactsDir() + "DocumentBase.ResourceLoadingCallback.docx");
  }
  
  /// <summary>
  /// Allows us to load images into a document using predefined shorthands, as opposed to URIs.
  /// This will separate image loading logic from the rest of the document construction.
  /// </summary>
  private static class ImageNameHandler implements IResourceLoadingCallback {
      public int resourceLoading(final ResourceLoadingArgs args) throws URISyntaxException, IOException {
          if (args.getResourceType() == ResourceType.IMAGE) {
              // If this callback encounters one of the image shorthands while loading an image,
          // it will apply unique logic for each defined shorthand instead of treating it as a URI.
              if ("Google logo".equals(args.getOriginalUri())) {
                  args.setData(DocumentHelper.getBytesFromStream(new URI("http://www.google.com/images/logos/ps_logo2.png").toURL().openStream()));
  
                  return ResourceLoadingAction.USER_PROVIDED;
              }
  
              if ("Aspose logo".equals(args.getOriginalUri())) {
                  args.setData(DocumentHelper.getBytesFromStream(getAsposelogoUri().toURL().openStream()));
  
                  return ResourceLoadingAction.USER_PROVIDED;
              }
  
              if ("Watermark".equals(args.getOriginalUri())) {
                  InputStream imageStream = new FileInputStream(getImageDir() + "Transparent background logo.png");
                  args.setData(DocumentHelper.getBytesFromStream(imageStream));
  
                  return ResourceLoadingAction.USER_PROVIDED;
              }
          }
  
          return ResourceLoadingAction.DEFAULT;
      }
  }

• getRevisions

  public RevisionCollection getRevisions()
  

  Gets a collection of revisions (tracked changes) that exist in this document.

  The returned collection is a "live" collection, which means if you remove parts of a document that contain revisions, the deleted revisions will automatically disappear from this collection.

• getRevisionsView/setRevisionsView

  public int getRevisionsView() / public void setRevisionsView(int value)
  

  Gets or sets a value indicating whether to work with the original or revised version of a document. The value of the property is RevisionsView integer constant.

  The default value is RevisionsView.ORIGINAL.

  Example:

  Shows how to switch between the revised and the original view of a document.

  Document doc = new Document(getMyDir() + "Revisions at list levels.docx");
  doc.updateListLabels();
  
  ParagraphCollection paragraphs = doc.getFirstSection().getBody().getParagraphs();
  Assert.assertEquals("1.", paragraphs.get(0).getListLabel().getLabelString());
  Assert.assertEquals("a.", paragraphs.get(1).getListLabel().getLabelString());
  Assert.assertEquals("", paragraphs.get(2).getListLabel().getLabelString());
  
  // View the document object as if all the revisions are accepted. Currently supports list labels.
  doc.setRevisionsView(RevisionsView.FINAL);
  
  Assert.assertEquals("", paragraphs.get(0).getListLabel().getLabelString());
  Assert.assertEquals("1.", paragraphs.get(1).getListLabel().getLabelString());
  Assert.assertEquals("a.", paragraphs.get(2).getListLabel().getLabelString());

• getSections

  public SectionCollection getSections()
  

  Returns a collection that represents all sections in the document.

  Example:

  Shows how to add/remove sections in a document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.write("Section 1");
  builder.insertBreak(BreakType.SECTION_BREAK_NEW_PAGE);
  builder.write("Section 2");
  
  // This shows what is in the document originally. The document has two sections
  Assert.assertEquals("Section 1\fSection 2", doc.getText().trim());
  
  // Delete the first section from the document
  doc.getSections().removeAt(0);
  
  // Duplicate the last section and append the copy to the end of the document
  int lastSectionIdx = doc.getSections().getCount() - 1;
  Section newSection = doc.getSections().get(lastSectionIdx).deepClone();
  doc.getSections().add(newSection);
  
  // Check what the document contains after we changed it
  Assert.assertEquals("Section 2\fSection 2", doc.getText().trim());

  Example:

  Shows how to specify how the section starts, from a new page, on the same page or other.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Add text to the first section and that comes with a blank document,
  // then add a new section that starts a new page and give it text as well
  builder.writeln("This text is in section 1.");
  builder.insertBreak(BreakType.SECTION_BREAK_NEW_PAGE);
  builder.writeln("This text is in section 2.");
  
  // Section break types determine how a new section gets split from the previous section
  // By inserting a "SectionBreakNewPage" type section break, we've set this section's SectionStart value to "NewPage" 
  Assert.assertEquals(SectionStart.NEW_PAGE, doc.getSections().get(1).getPageSetup().getSectionStart());
  
  // Insert a new column section the same way
  builder.insertBreak(BreakType.SECTION_BREAK_NEW_COLUMN);
  builder.writeln("This text is in section 3.");
  
  Assert.assertEquals(SectionStart.NEW_COLUMN, doc.getSections().get(2).getPageSetup().getSectionStart());
  
  // We can change the types of section breaks by assigning different values to each section's SectionStart
  // Setting their values to "Continuous" will put no visible breaks between sections
  // and will leave all the content of this document on one page
  doc.getSections().get(1).getPageSetup().setSectionStart(SectionStart.CONTINUOUS);
  doc.getSections().get(2).getPageSetup().setSectionStart(SectionStart.CONTINUOUS);
  
  doc.save(getArtifactsDir() + "PageSetup.SetSectionStart.docx");

• getShadeFormData/setShadeFormData

  public boolean getShadeFormData() / public void setShadeFormData(boolean value)
  

  Specifies whether to turn on the gray shading on form fields.

  Example:

  Shows how to apply gray shading to form fields.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.write("Hello world! ");
  builder.insertTextInput("My form field", TextFormFieldType.REGULAR, "",
      "Text contents of form field, which are shaded in grey by default.", 0);
  
  // We can turn the grey shading off, so the bookmarked text will blend in with the other text.
  doc.setShadeFormData(useGreyShading);
  doc.save(getArtifactsDir() + "Document.ShadeFormData.docx");

• getShowGrammaticalErrors/setShowGrammaticalErrors

  public boolean getShowGrammaticalErrors() / public void setShowGrammaticalErrors(boolean value)
  

  Specifies whether to display grammar errors in this document.

  Example:

  Shows how to show/hide errors in the document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Insert two sentences with mistakes that would be picked up
  // by the spelling and grammar checkers in Microsoft Word.
  builder.writeln("There is a speling error in this sentence.");
  builder.writeln("Their is a grammatical error in this sentence.");
  
  // If these options are enabled, then spelling errors will be underlined
  // in the output document by a jagged red line, and a double blue line will highlight grammatical mistakes.
  doc.setShowGrammaticalErrors(showErrors);
  doc.setShowSpellingErrors(showErrors);
  
  doc.save(getArtifactsDir() + "Document.SpellingAndGrammarErrors.docx");

• getShowSpellingErrors/setShowSpellingErrors

  public boolean getShowSpellingErrors() / public void setShowSpellingErrors(boolean value)
  

  Specifies whether to display spelling errors in this document.

  Example:

  Shows how to show/hide errors in the document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Insert two sentences with mistakes that would be picked up
  // by the spelling and grammar checkers in Microsoft Word.
  builder.writeln("There is a speling error in this sentence.");
  builder.writeln("Their is a grammatical error in this sentence.");
  
  // If these options are enabled, then spelling errors will be underlined
  // in the output document by a jagged red line, and a double blue line will highlight grammatical mistakes.
  doc.setShowGrammaticalErrors(showErrors);
  doc.setShowSpellingErrors(showErrors);
  
  doc.save(getArtifactsDir() + "Document.SpellingAndGrammarErrors.docx");

• getStyles

  public StyleCollection getStyles()
  

  Returns a collection of styles defined in the document.

  For more information see the description of the StyleCollection class.

  Example:

  Shows how to access a document's style collection.

  Document doc = new Document();
  
  // A blank document comes with 4 styles by default
  Assert.assertEquals(4, doc.getStyles().getCount());
  
  Iterator<Style> stylesEnum = doc.getStyles().iterator();
  while (stylesEnum.hasNext()) {
      Style curStyle = stylesEnum.next();
      System.out.println(MessageFormat.format("Style name:\t\"{0}\", of type \"{1}\"", curStyle.getName(), curStyle.getType()));
      System.out.println(MessageFormat.format("\tSubsequent style:\t{0}", curStyle.getNextParagraphStyleName()));
      System.out.println(MessageFormat.format("\tIs heading:\t\t\t{0}", curStyle.isHeading()));
      System.out.println(MessageFormat.format("\tIs QuickStyle:\t\t{0}", curStyle.isQuickStyle()));
  
      Assert.assertEquals(curStyle.getDocument(), doc);
  }

  Example:

  Shows how to create and use a paragraph style with list formatting.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Create a paragraph style and specify some formatting for it
  Style style = doc.getStyles().add(StyleType.PARAGRAPH, "MyStyle1");
  style.getFont().setSize(24.0);
  style.getFont().setName("Verdana");
  style.getParagraphFormat().setSpaceAfter(12.0);
  
  // Create a list and make sure the paragraphs that use this style will use this list
  style.getListFormat().setList(doc.getLists().add(ListTemplate.BULLET_DEFAULT));
  style.getListFormat().setListLevelNumber(0);
  
  // Apply the paragraph style to the current paragraph in the document and add some text
  builder.getParagraphFormat().setStyle(style);
  builder.writeln("Hello World: MyStyle1, bulleted list.");
  
  // Change to a paragraph style that has no list formatting
  builder.getParagraphFormat().setStyle(doc.getStyles().get("Normal"));
  builder.writeln("Hello World: Normal.");
  
  builder.getDocument().save(getArtifactsDir() + "Styles.ParagraphStyleBulletedList.docx");

  See Also:

  StyleCollection, Style

• getTheme

  public Theme getTheme()
  

  Gets the Theme object for this document.

  Example:

  Shows how to set custom theme colors and fonts.

  Document doc = new Document(getMyDir() + "Theme colors.docx");
  
  // This object gives us access to the document theme, which is a source of default fonts and colors
  Theme theme = doc.getTheme();
  
  // These fonts will be inherited by some styles like "Heading 1" and "Subtitle"
  theme.getMajorFonts().setLatin("Courier New");
  theme.getMinorFonts().setLatin("Agency FB");
  
  Assert.assertEquals(theme.getMajorFonts().getComplexScript(), "");
  Assert.assertEquals(theme.getMajorFonts().getEastAsian(), "");
  Assert.assertEquals(theme.getMinorFonts().getComplexScript(), "");
  Assert.assertEquals(theme.getMinorFonts().getEastAsian(), "");
  
  // This collection of colors corresponds to the color palette from Microsoft Word which appears when changing shading or font color 
  ThemeColors colors = theme.getColors();
  
  // We will set the color of each color palette column going from left to right like this
  colors.setDark1(Color.BLUE);
  colors.setLight1(Color.GREEN);
  colors.setDark2(Color.MAGENTA);
  colors.setLight2(Color.BLACK);
  
  colors.setAccent1(Color.RED);
  colors.setAccent2(Color.PINK);
  colors.setAccent3(Color.YELLOW);
  colors.setAccent4(Color.orange);
  colors.setAccent5(Color.cyan);
  colors.setAccent6(Color.darkGray);
  
  // We can also set colors for hyperlinks like this
  colors.setHyperlink(Color.WHITE);
  colors.setFollowedHyperlink(Color.lightGray);
  
  doc.save(getArtifactsDir() + "Themes.CustomColorsAndFonts.docx");

• getTrackRevisions/setTrackRevisions

  public boolean getTrackRevisions() / public void setTrackRevisions(boolean value)
  

  True if changes are tracked when this document is edited in Microsoft Word.

  Setting this option only instructs Microsoft Word whether the track changes is turned on or off. This property has no effect on changes to the document that you make programmatically via Aspose.Words.

  If you want to automatically track changes as they are made programmatically by Aspose.Words to this document use the startTrackRevisions(java.lang.String,java.util.Date) method.

• getVariables

  public VariableCollection getVariables()
  

  Returns the collection of variables added to a document or template.

  Example:

  Shows how to work with a document's variable collection.

  Document doc = new Document();
  VariableCollection variables = doc.getVariables();
  
  // Documents have a variable collection to which name/value pairs can be added
  variables.add("Home address", "123 Main St.");
  variables.add("City", "London");
  variables.add("Bedrooms", "3");
  
  Assert.assertEquals(3, variables.getCount());
  
  // Variables can be referenced and have their values presented in the document by DOCVARIABLE fields
  DocumentBuilder builder = new DocumentBuilder(doc);
  FieldDocVariable field = (FieldDocVariable) builder.insertField(FieldType.FIELD_DOC_VARIABLE, true);
  field.setVariableName("Home address");
  field.update();
  
  Assert.assertEquals("123 Main St.", field.getResult());
  
  // Assigning values to existing keys will update them
  variables.add("Home address", "456 Queen St.");
  
  // DOCVARIABLE fields also need to be updated in order to show an accurate up to date value
  field.update();
  
  Assert.assertEquals("456 Queen St.", field.getResult());
  
  // The existence of variables can be looked up either by name or value like this
  Assert.assertTrue(variables.contains("City"));
  
  // Variables are automatically sorted in alphabetical order
  Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
  Assert.assertEquals(1, variables.indexOfKey("City"));
  Assert.assertEquals(2, variables.indexOfKey("Home address"));
  
  // Variables can be removed either by name or index, or the entire collection can be cleared at once
  variables.remove("City");
  
  Assert.assertFalse(variables.contains("City"));
  
  variables.removeAt(1);
  
  Assert.assertFalse(variables.contains("Home address"));
  
  variables.clear();

• getVbaProject/setVbaProject

  public VbaProject getVbaProject() / public void setVbaProject(VbaProject value)
  

  Gets or sets a VbaProject.

  Example:

  Shows how to access a document's VBA project information.

  Document doc = new Document(getMyDir() + "VBA project.docm");
  
  // A VBA project contains a collection of VBA modules.
  VbaProject vbaProject = doc.getVbaProject();
  System.out.println(vbaProject.isSigned()
          ? MessageFormat.format("Project name: {0} signed; Project code page: {1}; Modules count: {2}\n", vbaProject.getName(), vbaProject.getCodePage(), vbaProject.getModules().getCount())
          : MessageFormat.format("Project name: {0} not signed; Project code page: {1}; Modules count: {2}\n", vbaProject.getName(), vbaProject.getCodePage(), vbaProject.getModules().getCount()));
  
  VbaModuleCollection vbaModules = doc.getVbaProject().getModules();
  
  Assert.assertEquals(vbaModules.getCount(), 3);
  
  for (VbaModule module : vbaModules) {
      System.out.println(MessageFormat.format("Module name: {0};\nModule code:\n{1}\n", module.getName(), module.getSourceCode()));
  }
  
  // Set new source code for VBA module. You can access VBA modules in the collection either by index or by name.
  vbaModules.get(0).setSourceCode("Your VBA code...");
  vbaModules.get("Module1").setSourceCode("Your VBA code...");
  
  // Remove a module from the collection.
  vbaModules.remove(vbaModules.get(2));

• getVersionsCount

  public int getVersionsCount()
  

  Gets the number of document versions that was stored in the DOC document.

  Versions in Microsoft Word are accessed via the File/Versions menu. Microsoft Word supports versions only for DOC files.

  This property allows to detect if there were document versions stored in this document before it was opened in Aspose.Words. Aspose.Words provides no other support for document versions. If you save this document using Aspose.Words, the document will be saved without versions.

  Example:

  Shows how to work with the versions count feature of older Microsoft Word documents.

  Document doc = new Document(getMyDir() + "Versions.doc");
  
  // We can read this property of a document, but we cannot preserve it while saving.
  Assert.assertEquals(4, doc.getVersionsCount());
  
  doc.save(getArtifactsDir() + "Document.VersionsCount.doc");      
  doc = new Document(getArtifactsDir() + "Document.VersionsCount.doc");
  
  Assert.assertEquals(0, doc.getVersionsCount());

• getViewOptions

  public ViewOptions getViewOptions()
  

  Provides options to control how the document is displayed in Microsoft Word.

  Example:

  Shows how to make sure the document is displayed at 50% zoom when opened in Microsoft Word.

  Document doc = new Document(getMyDir() + "Document.docx");
  
  // We can set the zoom factor to a percentage
  doc.getViewOptions().setViewType(ViewType.PAGE_LAYOUT);
  doc.getViewOptions().setZoomPercent(50);
  
  // Or we can set the ZoomType to a different value to avoid using percentages 
  Assert.assertEquals(ZoomType.NONE, doc.getViewOptions().getZoomType());
  
  doc.save(getArtifactsDir() + "ViewOptions.SetZoom.docx");

• getWarningCallback/setWarningCallback

  public IWarningCallback getWarningCallback() / public void setWarningCallback(IWarningCallback value)
  

  Called during various document processing procedures when an issue is detected that might result in data or formatting fidelity loss.

  Document may generate warnings at any stage of its existence, so it's important to setup warning callback as early as possible to avoid the warnings loss. E.g. such properties as PageCount actually build the document layout which is used later for rendering, and the layout warnings may be lost if warning callback is specified just for the rendering calls later.

  Example:

  Demonstrates how to receive notifications of font substitutions by using IWarningCallback.

  // Load the document to render
  Document doc = new Document(getMyDir() + "Document.docx");
  
  // Create a new class implementing IWarningCallback and assign it to the PdfSaveOptions class
  ExRendering.HandleDocumentWarnings callback = new ExRendering.HandleDocumentWarnings();
  doc.setWarningCallback(callback);
  
  // We can choose the default font to use in the case of any missing fonts
  FontSettings.getDefaultInstance().getSubstitutionSettings().getDefaultFontSubstitution().setDefaultFontName("Arial");
  
  // For testing we will set Aspose.Words to look for fonts only in a folder which doesn't exist. Since Aspose.Words won't
  // find any fonts in the specified directory, then during rendering the fonts in the document will be substituted with the default 
  // font specified under FontSettings.DefaultFontName. We can pick up on this substitution using our callback
  FontSettings.getDefaultInstance().setFontsFolder("", false);
  
  // Pass the save options along with the save path to the save method
  doc.save(getArtifactsDir() + "Font.SubstitutionNotification.pdf");

  Example:

  Shows how to set the property for finding the closest match font among the available font sources instead missing font.

  @Test
  public void enableFontSubstitution() throws Exception {
      Document doc = new Document(getMyDir() + "Missing font.docx");
  
      // Assign a custom warning callback
      HandleDocumentSubstitutionWarnings substitutionWarningHandler = new HandleDocumentSubstitutionWarnings();
      doc.setWarningCallback(substitutionWarningHandler);
  
      // Set a default font name and enable font substitution
      FontSettings fontSettings = new FontSettings();
      fontSettings.getSubstitutionSettings().getDefaultFontSubstitution().setDefaultFontName("Arial");
      fontSettings.getSubstitutionSettings().getFontInfoSubstitution().setEnabled(true);
  
      // When saving the document with the missing font, we should get a warning
      doc.setFontSettings(fontSettings);
      doc.save(getArtifactsDir() + "Font.EnableFontSubstitution.pdf");
  
      // List all warnings using an enumerator
      Iterator<WarningInfo> warnings = substitutionWarningHandler.FontWarnings.iterator();
      while (warnings.hasNext())
          System.out.println(warnings.next().getDescription());
  
      // Warnings are stored in this format
      Assert.assertEquals(WarningSource.LAYOUT, substitutionWarningHandler.FontWarnings.get(0).getSource());
      Assert.assertEquals("Font '28 Days Later' has not been found. Using 'Calibri' font instead. Reason: alternative name from document.",
              substitutionWarningHandler.FontWarnings.get(0).getDescription());
  
      // The warning info collection can also be cleared like this
      substitutionWarningHandler.FontWarnings.clear();
  
      Assert.assertEquals(substitutionWarningHandler.FontWarnings.getCount(), 0);
  }
  
  public static class HandleDocumentSubstitutionWarnings implements IWarningCallback {
      /// <summary>
      /// Our callback only needs to implement the "Warning" method. This method is called whenever there is a
      /// potential issue during document processing. The callback can be set to listen for warnings generated during document
      /// load and/or document save.
      /// </summary>
      public void warning(WarningInfo info) {
          // We are only interested in fonts being substituted
          if (info.getWarningType() == WarningType.FONT_SUBSTITUTION)
              FontWarnings.warning(info);
      }
  
      public WarningInfoCollection FontWarnings = new WarningInfoCollection();
  }

• getWatermark

  public Watermark getWatermark()
  

  Provides access to the document watermark.

• getWebExtensionTaskPanes

  public TaskPaneCollection getWebExtensionTaskPanes()
  

  Returns a collection that represents a list of task pane add-ins.

• getWriteProtection

  public WriteProtection getWriteProtection()
  

  Provides access to the document write protection options.

  Example:

  Shows how to protect a document with a password.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.writeln("Hello world! This document is protected.");
  
  // Enter a password up to 15 characters in length, and then verify the document's protection status.
  doc.getWriteProtection().setPassword("MyPassword");
  doc.getWriteProtection().setReadOnlyRecommended(true);
  
  Assert.assertTrue(doc.getWriteProtection().isWriteProtected());
  Assert.assertTrue(doc.getWriteProtection().validatePassword("MyPassword"));
  
  // Protection does not prevent the document from being edited programmatically, nor does it encrypt the contents.
  doc.save(getArtifactsDir() + "Document.WriteProtection.docx");
  doc = new Document(getArtifactsDir() + "Document.WriteProtection.docx");
  
  Assert.assertTrue(doc.getWriteProtection().isWriteProtected());
  
  builder = new DocumentBuilder(doc);
  builder.moveToDocumentEnd();
  builder.writeln("Writing text in a protected document.");
  
  Assert.assertEquals("Hello world! This document is protected." +
                  "\rWriting text in a protected document.", doc.getText().trim());

Method Detail

• accept

  public boolean accept(DocumentVisitor visitor)
                throws java.lang.Exception

  Accepts a visitor.

  Enumerates over this node and all of its children. Each node calls a corresponding method on DocumentVisitor.

  For more info see the Visitor design pattern.

  Calls DocumentVisitor.VisitDocumentStart, then calls Accept for all child nodes of the document and calls DocumentVisitor.VisitDocumentEnd at the end.

  Parameters:

  visitor - The visitor that will visit the nodes.

  Returns:

  True if all nodes were visited; false if DocumentVisitor stopped the operation before visiting all nodes.

  Example:

  Shows how to use a document visitor to print a document's node structure.

  public void docStructureToText() throws Exception {
      Document doc = new Document(getMyDir() + "DocumentVisitor-compatible features.docx");
      DocStructurePrinter visitor = new DocStructurePrinter();
  
      // When we get a composite node to accept a document visitor, the visitor visits the accepting node,
      // and then traverses all of the node's children in a depth-first manner.
      // The visitor can read and modify each visited node.
      doc.accept(visitor);
  
      System.out.println(visitor.getText());
  }
  
  /// <summary>
  /// Traverses a node's tree of child nodes, and creates a map of this tree in the form of a string.
  /// </summary>
  public static class DocStructurePrinter extends DocumentVisitor {
      public DocStructurePrinter() {
          mAcceptingNodeChildTree = new StringBuilder();
      }
  
      public String getText() {
          return mAcceptingNodeChildTree.toString();
      }
  
      /// <summary>
      /// Called when a Document node is encountered.
      /// </summary>
      public int visitDocumentStart(Document doc) {
          int childNodeCount = doc.getChildNodes(NodeType.ANY, true).getCount();
  
          indentAndAppendLine("[Document start] Child nodes: " + childNodeCount);
          mDocTraversalDepth++;
  
          // Allow the visitor to continue visiting other nodes.
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called after all the child nodes of a Document node have been visited.
      /// </summary>
      public int visitDocumentEnd(Document doc) {
          mDocTraversalDepth--;
          indentAndAppendLine("[Document end]");
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called when a Section node is encountered in the document.
      /// </summary>
      public int visitSectionStart(final Section section) {
          // Get the index of our section within the document
          NodeCollection docSections = section.getDocument().getChildNodes(NodeType.SECTION, false);
          int sectionIndex = docSections.indexOf(section);
  
          indentAndAppendLine("[Section start] Section index: " + sectionIndex);
          mDocTraversalDepth++;
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called after all the child nodes of a Section node have been visited.
      /// </summary>
      public int visitSectionEnd(final Section section) {
          mDocTraversalDepth--;
          indentAndAppendLine("[Section end]");
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called when a Body node is encountered in the document.
      /// </summary>
      public int visitBodyStart(final Body body) {
          int paragraphCount = body.getParagraphs().getCount();
          indentAndAppendLine("[Body start] Paragraphs: " + paragraphCount);
          mDocTraversalDepth++;
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called after all the child nodes of a Body node have been visited.
      /// </summary>
      public int visitBodyEnd(final Body body) {
          mDocTraversalDepth--;
          indentAndAppendLine("[Body end]");
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called when a Paragraph node is encountered in the document.
      /// </summary>
      public int visitParagraphStart(final Paragraph paragraph) {
          indentAndAppendLine("[Paragraph start]");
          mDocTraversalDepth++;
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called after all the child nodes of a Paragraph node have been visited.
      /// </summary>
      public int visitParagraphEnd(final Paragraph paragraph) {
          mDocTraversalDepth--;
          indentAndAppendLine("[Paragraph end]");
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called when a Run node is encountered in the document.
      /// </summary>
      public int visitRun(final Run run) {
          indentAndAppendLine("[Run] \"" + run.getText() + "\"");
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Called when a SubDocument node is encountered in the document.
      /// </summary>
      public int visitSubDocument(final SubDocument subDocument) {
          indentAndAppendLine("[SubDocument]");
  
          return VisitorAction.CONTINUE;
      }
  
      /// <summary>
      /// Append a line to the StringBuilder and indent it depending on how deep the visitor is into the document tree.
      /// </summary>
      /// <param name="text"></param>
      private void indentAndAppendLine(final String text) {
          for (int i = 0; i < mDocTraversalDepth; i++) {
              mAcceptingNodeChildTree.append("|  ");
          }
  
          mAcceptingNodeChildTree.append(text + "\r\n");
      }
  
      private int mDocTraversalDepth;
      private StringBuilder mAcceptingNodeChildTree;
  }

• acceptAllRevisions

  public void acceptAllRevisions()
                         throws java.lang.Exception

  Accepts all tracked changes in the document.

  This method is a shortcut for RevisionCollection.acceptAll().

  Example:

  Shows how to accept all tracking changes in the document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Edit the document while tracking changes to create a few revisions.
  doc.startTrackRevisions("John Doe");
  builder.write("Hello world! ");
  builder.write("Hello again! "); 
  builder.write("This is another revision.");
  doc.stopTrackRevisions();
  
  Assert.assertEquals(3, doc.getRevisions().getCount());
  
  // We can iterate through every revision and accept/reject it as a part of our document.
  // If we know we wish to accept every revision, we can do it more straightforwardly so by calling this method.
  doc.acceptAllRevisions();
  
  Assert.assertEquals(0, doc.getRevisions().getCount());
  Assert.assertEquals("Hello world! Hello again! This is another revision.", doc.getText().trim());

• appendChild

  public Node appendChild(Node newChild)

  Adds the specified node to the end of the list of child nodes for this node.

  If the newChild is already in the tree, it is first removed.

  If the node being inserted was created from another document, you should use importNode(com.aspose.words.Node,boolean,int) to import the node to the current document. The imported node can then be inserted into the current document.

  Parameters:

  newChild - The node to add.

  Returns:

  The node added.

  Example:

  Shows how to construct an Aspose Words document node by node.

  Document doc = new Document();
  
  // A newly created blank document still comes one section, one body and one paragraph
  // Calling this method will remove all those nodes to completely empty the document
  doc.removeAllChildren();
  
  // This document now has no composite nodes that content can be added to
  // If we wish to edit it, we will need to repopulate its node collection,
  // which we will start to do with by creating a new Section node
  Section section = new Section(doc);
  
  // Append the section to the document
  doc.appendChild(section);
  
  // Lets set some properties for the section
  section.getPageSetup().setSectionStart(SectionStart.NEW_PAGE);
  section.getPageSetup().setPaperSize(PaperSize.LETTER);
  
  // A section needs a body, which will contain all other nodes that can be edited
  Body body = new Body(doc);
  section.appendChild(body);
  
  // The body needs to have at least one paragraph
  // Note that the paragraph has not yet been added to the document, but we have to specify the parent document
  // The parent document is needed so the paragraph can correctly work
  // with styles and other document-wide information
  Paragraph para = new Paragraph(doc);
  body.appendChild(para);
  
  // We can set some formatting for the paragraph
  para.getParagraphFormat().setStyleName("Heading 1");
  para.getParagraphFormat().setAlignment(ParagraphAlignment.CENTER);
  
  // Now we can begin adding content to the document
  Run run = new Run(doc);
  run.setText("Hello World!");
  run.getFont().setColor(Color.RED);
  para.appendChild(run);
  
  Assert.assertEquals("Hello World!" + ControlChar.SECTION_BREAK_CHAR, doc.getText());
  
  doc.save(getArtifactsDir() + "Section.CreateFromScratch.docx");

• appendDocument

  public void appendDocument(Document srcDoc, int importFormatMode)

  Appends the specified document to the end of this document.

  Parameters:

  srcDoc - The document to append.

  importFormatMode - A ImportFormatMode value. Specifies how to merge style formatting that clashes.

  Example:

  Shows how to append all the documents in a folder to the end of a template document.

  Document dstDoc = new Document();
  
  DocumentBuilder builder = new DocumentBuilder(dstDoc);
  builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
  builder.writeln("Template Document");
  builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.NORMAL);
  builder.writeln("Some content here");
  
  // Append all unencrypted documents with the .doc extension
  // from our local file system directory to the base document.
  for (File fileName : new File(getMyDir()).listFiles((f, name) -> name.endsWith(".doc")))
  {
      FileFormatInfo info = FileFormatUtil.detectFileFormat(fileName.getPath());
      if (info.isEncrypted())
          continue;
  
      Document srcDoc = new Document(fileName.getPath());
      dstDoc.appendDocument(srcDoc, ImportFormatMode.USE_DESTINATION_STYLES);
  }
  
  dstDoc.save(getArtifactsDir() + "Document.AppendAllDocumentsInFolder.doc");

  Example:

  Shows how to append a document to the end of another document.

  Document srcDoc = new Document();
  srcDoc.getFirstSection().getBody().appendParagraph("Source document text. ");
  
  Document dstDoc = new Document();
  dstDoc.getFirstSection().getBody().appendParagraph("Destination document text. ");
  
  // Append the source document to the destination document while preserving its formatting,
  // then save the source document to the local file system.
  dstDoc.appendDocument(srcDoc, ImportFormatMode.KEEP_SOURCE_FORMATTING);
  
  dstDoc.save(getArtifactsDir() + "Document.AppendDocument.docx");

• appendDocument

  public void appendDocument(Document srcDoc, int importFormatMode, ImportFormatOptions importFormatOptions)

  Appends the specified document to the end of this document.

  Parameters:

  srcDoc - The document to append.

  importFormatMode - A ImportFormatMode value. Specifies how to merge style formatting that clashes.

  importFormatOptions - Allows to specify options that affect formatting of a result document.

  Example:

  Shows how to manage list style clashes while appending a document.

  // Open a document with text in a custom style, and clone it.
  Document srcDoc = new Document(getMyDir() + "Custom list numbering.docx");
  Document dstDoc = srcDoc.deepClone();
  
  // We now have two documents, each with an identical style named "CustomStyle".
  // Change the text color for one of the styles to set it apart from the other.
  dstDoc.getStyles().get("CustomStyle").getFont().setColor(Color.RED);
  
  // If there is a clash of list styles, apply the list format of the source document.
  ImportFormatOptions options = new ImportFormatOptions();
  options.setKeepSourceNumbering(true);
  
  // Joining two documents that have different styles that share the same name causes a style clash.
  // We can specify an import format mode while appending documents to resolve this clash.
  dstDoc.appendDocument(srcDoc, ImportFormatMode.KEEP_DIFFERENT_STYLES, options);
  dstDoc.updateListLabels();
  
  dstDoc.save(getArtifactsDir() + "DocumentBuilder.AppendDocumentAndResolveStyles.docx");

• cleanup

  public void cleanup()
              throws java.lang.Exception

  Cleans unused styles and lists from the document.

  Example:

  Shows how to remove unused custom styles from a document.

  Document doc = new Document();
  
  doc.getStyles().add(StyleType.LIST, "MyListStyle1");
  doc.getStyles().add(StyleType.LIST, "MyListStyle2");
  doc.getStyles().add(StyleType.CHARACTER, "MyParagraphStyle1");
  doc.getStyles().add(StyleType.CHARACTER, "MyParagraphStyle2");
  
  // Combined with the built-in styles, the document now has eight styles.
  // A custom style counts as "used" while applied to some part of the document,
  // which means that the four styles we added are currently unused.
  Assert.assertEquals(8, doc.getStyles().getCount());
  
  // Apply a custom character style, and then a custom list style. Doing so will mark the styles as "used".
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.getFont().setStyle(doc.getStyles().get("MyParagraphStyle1"));
  builder.writeln("Hello world!");
  
  List list = doc.getLists().add(doc.getStyles().get("MyListStyle1"));
  builder.getListFormat().setList(list);
  builder.writeln("Item 1");
  builder.writeln("Item 2");
  
  doc.cleanup();
  
  Assert.assertEquals(6, doc.getStyles().getCount());
  
  // Removing every node that a custom style is applied to marks it as "unused" again.
  // Run the Cleanup method again to remove them.
  doc.getFirstSection().getBody().removeAllChildren();
  doc.cleanup();
  
  Assert.assertEquals(4, doc.getStyles().getCount());

• cleanup

  public void cleanup(CleanupOptions options)
              throws java.lang.Exception

  Cleans unused styles and lists from the document depending on given CleanupOptions.

• compare

  public void compare(Document document, java.lang.String author, java.util.Date dateTime)
              throws java.lang.Exception

  Compares this document with another document producing changes as number of edit and format revisions Revision.

  The following document nodes are not compared at the moment:

  • StructuredDocumentTag
  • Item3

  Note: Documents must not have revisions before comparison.

  Parameters:

  document - Document to compare.

  author - Initials of the author to use for revisions.

  dateTime - The date and time to use for revisions.

  Example:

  Shows how to compare documents.

  Document docOriginal = new Document();
  DocumentBuilder builder = new DocumentBuilder(docOriginal);
  builder.writeln("This is the original document.");
  
  Document docEdited = new Document();
  builder = new DocumentBuilder(docEdited);
  builder.writeln("This is the edited document.");
  
  // Comparing documents with revisions will throw an exception.
  if (docOriginal.getRevisions().getCount() == 0 && docEdited.getRevisions().getCount() == 0)
      docOriginal.compare(docEdited, "authorName", new Date());
  
  // After the comparison, the original document will gain a new revision
  // for every element that's different in the edited document.
  for (Revision r : docOriginal.getRevisions())
  {
      System.out.println("Revision type: {r.RevisionType}, on a node of type \"{r.ParentNode.NodeType}\"");
      System.out.println("\tChanged text: \"{r.ParentNode.GetText()}\"");
  }
  
  // Accepting these revisions will transform the original document into the edited document.
  docOriginal.getRevisions().acceptAll();
  
  Assert.assertEquals(docOriginal.getText(), docEdited.getText());

• compare

  public void compare(Document document, java.lang.String author, java.util.Date dateTime, CompareOptions options)
              throws java.lang.Exception

  Compares this document with another document producing changes as a number of edit and format revisions Revision. Allows to specify comparison options using CompareOptions.

  Example:

  Shows how to filter specific types of document elements when making a comparison.

  // Create the original document, and populate it with various kinds of elements.
  Document docOriginal = new Document();
  DocumentBuilder builder = new DocumentBuilder(docOriginal);
  
  // Paragraph text referenced with an endnote:
  builder.writeln("Hello world! This is the first paragraph.");
  builder.insertFootnote(FootnoteType.ENDNOTE, "Original endnote text.");
  
  // Table:
  builder.startTable();
  builder.insertCell();
  builder.write("Original cell 1 text");
  builder.insertCell();
  builder.write("Original cell 2 text");
  builder.endTable();
  
  // Textbox:
  Shape textBox = builder.insertShape(ShapeType.TEXT_BOX, 150.0, 20.0);
  builder.moveTo(textBox.getFirstParagraph());
  builder.write("Original textbox contents");
  
  // DATE field:
  builder.moveTo(docOriginal.getFirstSection().getBody().appendParagraph(""));
  builder.insertField(" DATE ");
  
  // Comment:
  Comment newComment = new Comment(docOriginal, "John Doe", "J.D.", new Date());
  newComment.setText("Original comment.");
  builder.getCurrentParagraph().appendChild(newComment);
  
  // Header:
  builder.moveToHeaderFooter(HeaderFooterType.HEADER_PRIMARY);
  builder.writeln("Original header contents.");
  
  // Create a clone of our document, and perform a quick edit on each of the cloned document's elements.
  Document docEdited = (Document)docOriginal.deepClone(true);
  Paragraph firstParagraph = docEdited.getFirstSection().getBody().getFirstParagraph();
  
  firstParagraph.getRuns().get(0).setText("hello world! this is the first paragraph, after editing.");
  firstParagraph.getParagraphFormat().setStyle(docEdited.getStyles().getByStyleIdentifier(StyleIdentifier.HEADING_1));
  ((Footnote)docEdited.getChild(NodeType.FOOTNOTE, 0, true)).getFirstParagraph().getRuns().get(1).setText("Edited endnote text.");
  ((Table)docEdited.getChild(NodeType.TABLE, 0, true)).getFirstRow().getCells().get(1).getFirstParagraph().getRuns().get(0).setText("Edited Cell 2 contents");
  ((Shape)docEdited.getChild(NodeType.SHAPE, 0, true)).getFirstParagraph().getRuns().get(0).setText("Edited textbox contents");
  ((FieldDate)docEdited.getRange().getFields().get(0)).setUseLunarCalendar(true); 
  ((Comment)docEdited.getChild(NodeType.COMMENT, 0, true)).getFirstParagraph().getRuns().get(0).setText("Edited comment.");
  docEdited.getFirstSection().getHeadersFooters().getByHeaderFooterType(HeaderFooterType.HEADER_PRIMARY).getFirstParagraph().getRuns().get(0).setText("Edited header contents.");
  
  // Comparing documents creates a revision for every edit in the edited document.
  // A CompareOptions object has a series of flags that can suppress revisions
  // on each respective type of element, effectively ignoring their change.
  CompareOptions compareOptions = new CompareOptions();
  compareOptions.setIgnoreFormatting(false);
  compareOptions.setIgnoreCaseChanges(false);
  compareOptions.setIgnoreComments(false);
  compareOptions.setIgnoreTables(false);
  compareOptions.setIgnoreFields(false);
  compareOptions.setIgnoreFootnotes(false);
  compareOptions.setIgnoreTextboxes(false);
  compareOptions.setIgnoreHeadersAndFooters(false);
  compareOptions.setTarget(ComparisonTargetType.NEW);
  
  docOriginal.compare(docEdited, "John Doe", new Date(), compareOptions);
  docOriginal.save(getArtifactsDir() + "Document.CompareOptions.docx");

• copyStylesFromTemplate

  public void copyStylesFromTemplate(Document template)

  Copies styles from the specified template to a document.

  When styles are copied from a template to a document, like-named styles in the document are redefined to match the style descriptions in the template. Unique styles from the template are copied to the document. Unique styles in the document remain intact.

  Example:

  Shows how to copy styles from one document to another.

  // Create a document, and then add styles that we will copy to another document.
  Document template = new Document();
  
  Style style = template.getStyles().add(StyleType.PARAGRAPH, "TemplateStyle1");
  style.getFont().setName("Times New Roman");
  style.getFont().setColor(Color.WHITE);
  
  style = template.getStyles().add(StyleType.PARAGRAPH, "TemplateStyle2");
  style.getFont().setName("Arial");
  style.getFont().setColor(Color.RED);
  
  style = template.getStyles().add(StyleType.PARAGRAPH, "TemplateStyle3");
  style.getFont().setName("Courier New");
  style.getFont().setColor(Color.BLUE);
  
  Assert.assertEquals(7, template.getStyles().getCount());
  
  // Create a document which we will copy the styles to.
  Document target = new Document();
  
  // Create a style with the same name as a style from the template document, and add it to the target document.
  style = target.getStyles().add(StyleType.PARAGRAPH, "TemplateStyle3");
  style.getFont().setName("Calibri");
  style.getFont().setColor(Color.ORANGE);
  
  Assert.assertEquals(5, target.getStyles().getCount());
  
  // There are two ways of calling the method to copy all the styles from one document to another.
  // 1 -  Passing the template document object:
  target.copyStylesFromTemplate(template);
  
  // Copying styles adds all styles from the template document to the target
  // and overwrites existing styles with the same name.
  Assert.assertEquals(7, target.getStyles().getCount());
  
  Assert.assertEquals("Courier New", target.getStyles().get("TemplateStyle3").getFont().getName());
  Assert.assertEquals(Color.BLUE.getRGB(), target.getStyles().get("TemplateStyle3").getFont().getColor().getRGB());
  
  // 2 -  Passing the local system filename of a template document:
  target.copyStylesFromTemplate(getMyDir() + "Rendering.docx");
  
  Assert.assertEquals(21, target.getStyles().getCount());

  Example:

  Shows how to copies styles from the template to a document via Document.

  Document template = new Document(getMyDir() + "Rendering.docx");
  Document target = new Document(getMyDir() + "Document.docx");
  
  target.copyStylesFromTemplate(template);

• copyStylesFromTemplate

  public void copyStylesFromTemplate(java.lang.String template)
                             throws java.lang.Exception

  Copies styles from the specified template to a document.

  When styles are copied from a template to a document, like-named styles in the document are redefined to match the style descriptions in the template. Unique styles from the template are copied to the document. Unique styles in the document remain intact.

  Example:

  Shows how to copy styles from one document to another.

  // Create a document, and then add styles that we will copy to another document.
  Document template = new Document();
  
  Style style = template.getStyles().add(StyleType.PARAGRAPH, "TemplateStyle1");
  style.getFont().setName("Times New Roman");
  style.getFont().setColor(Color.WHITE);
  
  style = template.getStyles().add(StyleType.PARAGRAPH, "TemplateStyle2");
  style.getFont().setName("Arial");
  style.getFont().setColor(Color.RED);
  
  style = template.getStyles().add(StyleType.PARAGRAPH, "TemplateStyle3");
  style.getFont().setName("Courier New");
  style.getFont().setColor(Color.BLUE);
  
  Assert.assertEquals(7, template.getStyles().getCount());
  
  // Create a document which we will copy the styles to.
  Document target = new Document();
  
  // Create a style with the same name as a style from the template document, and add it to the target document.
  style = target.getStyles().add(StyleType.PARAGRAPH, "TemplateStyle3");
  style.getFont().setName("Calibri");
  style.getFont().setColor(Color.ORANGE);
  
  Assert.assertEquals(5, target.getStyles().getCount());
  
  // There are two ways of calling the method to copy all the styles from one document to another.
  // 1 -  Passing the template document object:
  target.copyStylesFromTemplate(template);
  
  // Copying styles adds all styles from the template document to the target
  // and overwrites existing styles with the same name.
  Assert.assertEquals(7, target.getStyles().getCount());
  
  Assert.assertEquals("Courier New", target.getStyles().get("TemplateStyle3").getFont().getName());
  Assert.assertEquals(Color.BLUE.getRGB(), target.getStyles().get("TemplateStyle3").getFont().getColor().getRGB());
  
  // 2 -  Passing the local system filename of a template document:
  target.copyStylesFromTemplate(getMyDir() + "Rendering.docx");
  
  Assert.assertEquals(21, target.getStyles().getCount());

• deepClone

  public Document deepClone()

  Performs a deep copy of the Document.

  Returns:

  The cloned document.

  Example:

  Shows how to deep clone a document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.write("Hello world!");
  
  // Cloning will produce a new document with the same contents as the original,
  // but with a unique copy of each of the original document's nodes.
  Document clone = doc.deepClone();
  
  Assert.assertEquals(doc.getFirstSection().getBody().getFirstParagraph().getRuns().get(0).getText(), 
      clone.getFirstSection().getBody().getFirstParagraph().getRuns().get(0).getText());
  Assert.assertNotEquals(doc.getFirstSection().getBody().getFirstParagraph().getRuns().get(0).hashCode(),
      clone.getFirstSection().getBody().getFirstParagraph().getRuns().get(0).hashCode());

• deepClone

  public Node deepClone(boolean isCloneChildren)

  Creates a duplicate of the node.

  This method serves as a copy constructor for nodes. The cloned node has no parent, but belongs to the same document as the original node.

  This method always performs a deep copy of the node. The isCloneChildren parameter specifies whether to perform copy all child nodes as well.

  Parameters:

  isCloneChildren - True to recursively clone the subtree under the specified node; false to clone only the node itself.

  Returns:

  The cloned node.

  Example:

  Shows how to clone composite nodes with and without their child nodes.

  Document doc = new Document();
  Paragraph para = doc.getFirstSection().getBody().getFirstParagraph();
  para.appendChild(new Run(doc, "Hello world!"));
  
  // Clone the paragraph and the child nodes
  Node cloneWithChildren = para.deepClone(true);
  
  Assert.assertTrue(((CompositeNode) cloneWithChildren).hasChildNodes());
  Assert.assertEquals("Hello world!", cloneWithChildren.getText().trim());
  
  // Clone the paragraph without its clild nodes
  Node cloneWithoutChildren = para.deepClone(false);
  
  Assert.assertFalse(((CompositeNode) cloneWithoutChildren).hasChildNodes());
  Assert.assertEquals("", cloneWithoutChildren.getText().trim());

• ensureMinimum

  public void ensureMinimum()

  If the document contains no sections, creates one section with one paragraph.

  Example:

  Shows how to ensure that a document contains the minimal set of nodes required for editing its contents.

  // A newly created document contains one child Section, which includes one child Body and one child Paragraph.
  // We can edit the document body's contents by adding nodes such as Runs or inline Shapes to that paragraph.
  Document doc = new Document();
  NodeCollection nodes = doc.getChildNodes(NodeType.ANY, true);
  
  Assert.assertEquals(NodeType.SECTION, nodes.get(0).getNodeType());
  Assert.assertEquals(doc, nodes.get(0).getParentNode());
  
  Assert.assertEquals(NodeType.BODY, nodes.get(1).getNodeType());
  Assert.assertEquals(nodes.get(0), nodes.get(1).getParentNode());
  
  Assert.assertEquals(NodeType.PARAGRAPH, nodes.get(2).getNodeType());
  Assert.assertEquals(nodes.get(1), nodes.get(2).getParentNode());
  
  // This is the minimal set of nodes that we need to be able to edit the document.
  // We will no longer be able to edit the document if we remove any of them.
  doc.removeAllChildren();
  
  Assert.assertEquals(0, doc.getChildNodes(NodeType.ANY, true).getCount());
  
  // Call this method to make sure that the document has at least those three nodes,
  // so we can edit the document again.
  doc.ensureMinimum();
  
  Assert.assertEquals(NodeType.SECTION, nodes.get(0).getNodeType());
  Assert.assertEquals(NodeType.BODY, nodes.get(1).getNodeType());
  Assert.assertEquals(NodeType.PARAGRAPH, nodes.get(2).getNodeType());
  
  ((Paragraph)nodes.get(2)).getRuns().add(new Run(doc, "Hello world!"));

• expandTableStylesToDirectFormatting

  public void expandTableStylesToDirectFormatting()
                                          throws java.lang.Exception

  Converts formatting specified in table styles into direct formatting on tables in the document.

  This method exists because this version of Aspose.Words provides only limited support for table styles (see below). This method might be useful when you load a DOCX or WordprocessingML document that contains tables formatted with table styles and you need to query formatting of tables, cells, paragraphs or text.

  This version of Aspose.Words provides limited support for table styles as follows:

  • Table styles defined in DOCX or WordprocessingML documents are preserved as table styles when saving the document as DOCX or WordprocessingML.
  • Table styles defined in DOCX or WordprocessingML documents are automatically converted to direct formatting on tables when saving the document into any other format, rendering or printing.
  • Table styles defined in DOC documents are preserved as table styles when saving the document as DOC only.

  Example:

  Shows how to apply attributes of a table's style directly to the table's elements.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  Table table = builder.startTable();
  builder.insertCell();
  builder.write("Hello world!");
  builder.endTable();
  
  TableStyle tableStyle = (TableStyle)doc.getStyles().add(StyleType.TABLE, "MyTableStyle1");
  tableStyle.setRowStripe(3);
  tableStyle.setCellSpacing(5.0);
  tableStyle.getShading().setBackgroundPatternColor(Color.WHITE);
  tableStyle.getBorders().setColor(Color.BLUE);
  tableStyle.getBorders().setLineStyle(LineStyle.DOT_DASH);
  
  table.setStyle(tableStyle);
  
  // This method concerns table style attributes such as the ones we set above.
  doc.expandTableStylesToDirectFormatting();
  
  doc.save(getArtifactsDir() + "Document.TableStyleToDirectFormatting.docx");

• extractPages

  public Document extractPages(int index, int count)
                       throws java.lang.Exception

  Returns the Document object representing specified range of pages.

  The resulting document should look like the one in MS Word, as if we had performed 'Print specific pages' – the numbering, headers/footers and cross tables layout will be preserved. But due to a large number of nuances, appearing while reducing the number of pages, full match of the layout is a quiet complicated task requiring a lot of effort. Depending on the document complexity there might be slight differences in the resulting document contents layout comparing to the source document. Any feedback would be greatly appreciated.

  Parameters:

  index - The zero-based index of the first page to extract.

  count - Number of pages to be extracted.

• getAncestor

  public CompositeNode getAncestor(int ancestorType)

  Gets the first ancestor of the specified NodeType.

  Parameters:

  ancestorType - A NodeType value. The node type of the ancestor to retrieve.

  Returns:

  The ancestor of the specified type or null if no ancestor of this type was found.

  Example:

  Shows how to find out if a table contains another table or if the table itself is nested inside another table.

  public void calculateDepthOfNestedTables() throws Exception {
      Document doc = new Document(getMyDir() + "Nested tables.docx");
      NodeCollection tables = doc.getChildNodes(NodeType.TABLE, true);
  
      for (int i = 0; i < tables.getCount(); i++) {
          // First lets find if any cells in the table have tables themselves as children
          int count = getChildTableCount((Table) tables.get(i));
          System.out.println(MessageFormat.format("Table #{0} has {1} tables directly within its cells", i, count));
  
          // Now let's try the other way around, lets try find if the table is nested inside another table and at what depth
          int tableDepth = getNestedDepthOfTable((Table) tables.get(i));
  
          if (tableDepth > 0)
              System.out.println(MessageFormat.format("Table #{0} is nested inside another table at depth of {1}", i, tableDepth));
          else
              System.out.println(MessageFormat.format("Table #{0} is a non nested table (is not a child of another table)", i));
      }
  }
  
  /**
   * Calculates what level a table is nested inside other tables.
   *
   * @returns An integer containing the level the table is nested at.
   * 0 = Table is not nested inside any other table
   * 1 = Table is nested within one parent table
   * 2 = Table is nested within two parent tables etc..
   */
  private static int getNestedDepthOfTable(final Table table) {
      int depth = 0;
  
      int type = table.getNodeType();
      // The parent of the table will be a Cell, instead attempt to find a grandparent that is of type Table
      Node parent = table.getAncestor(table.getNodeType());
  
      while (parent != null) {
          // Every time we find a table a level up we increase the depth counter and then try to find an
          // ancestor of type table from the parent
          depth++;
          parent = parent.getAncestor(Table.class);
      }
  
      return depth;
  }
  
  /**
   * Determines if a table contains any immediate child table within its cells.
   * Does not recursively traverse through those tables to check for further tables.
   *
   * @returns Returns true if at least one child cell contains a table.
   * Returns false if no cells in the table contains a table.
   */
  private static int getChildTableCount(final Table table) {
      int tableCount = 0;
      // Iterate through all child rows in the table
      for (Row row : table.getRows()) {
          // Iterate through all child cells in the row
          for (Cell cell : row.getCells()) {
              // Retrieve the collection of child tables of this cell
              TableCollection childTables = cell.getTables();
  
              // If this cell has a table as a child then return true
              if (childTables.getCount() > 0) tableCount++;
          }
      }
  
      // No cell contains a table
      return tableCount;
  }

• getAncestor

  public CompositeNode getAncestor(java.lang.Class ancestorType)

  Gets the first ancestor of the specified object type.

  The ancestor type matches if it is equal to ancestorType or derived from ancestorType.

  Parameters:

  ancestorType - The object type of the ancestor to retrieve.

  Returns:

  The ancestor of the specified type or null if no ancestor of this type was found.

  Example:

  Shows how to find out if a table contains another table or if the table itself is nested inside another table.

  public void calculateDepthOfNestedTables() throws Exception {
      Document doc = new Document(getMyDir() + "Nested tables.docx");
      NodeCollection tables = doc.getChildNodes(NodeType.TABLE, true);
  
      for (int i = 0; i < tables.getCount(); i++) {
          // First lets find if any cells in the table have tables themselves as children
          int count = getChildTableCount((Table) tables.get(i));
          System.out.println(MessageFormat.format("Table #{0} has {1} tables directly within its cells", i, count));
  
          // Now let's try the other way around, lets try find if the table is nested inside another table and at what depth
          int tableDepth = getNestedDepthOfTable((Table) tables.get(i));
  
          if (tableDepth > 0)
              System.out.println(MessageFormat.format("Table #{0} is nested inside another table at depth of {1}", i, tableDepth));
          else
              System.out.println(MessageFormat.format("Table #{0} is a non nested table (is not a child of another table)", i));
      }
  }
  
  /**
   * Calculates what level a table is nested inside other tables.
   *
   * @returns An integer containing the level the table is nested at.
   * 0 = Table is not nested inside any other table
   * 1 = Table is nested within one parent table
   * 2 = Table is nested within two parent tables etc..
   */
  private static int getNestedDepthOfTable(final Table table) {
      int depth = 0;
  
      int type = table.getNodeType();
      // The parent of the table will be a Cell, instead attempt to find a grandparent that is of type Table
      Node parent = table.getAncestor(table.getNodeType());
  
      while (parent != null) {
          // Every time we find a table a level up we increase the depth counter and then try to find an
          // ancestor of type table from the parent
          depth++;
          parent = parent.getAncestor(Table.class);
      }
  
      return depth;
  }
  
  /**
   * Determines if a table contains any immediate child table within its cells.
   * Does not recursively traverse through those tables to check for further tables.
   *
   * @returns Returns true if at least one child cell contains a table.
   * Returns false if no cells in the table contains a table.
   */
  private static int getChildTableCount(final Table table) {
      int tableCount = 0;
      // Iterate through all child rows in the table
      for (Row row : table.getRows()) {
          // Iterate through all child cells in the row
          for (Cell cell : row.getCells()) {
              // Retrieve the collection of child tables of this cell
              TableCollection childTables = cell.getTables();
  
              // If this cell has a table as a child then return true
              if (childTables.getCount() > 0) tableCount++;
          }
      }
  
      // No cell contains a table
      return tableCount;
  }

• getChild

  public Node getChild(int nodeType, int index, boolean isDeep)

  Returns an Nth child node that matches the specified type.

  If index is out of range, a null is returned.

  Note that markup nodes (NodeType.STRUCTURED_DOCUMENT_TAG and NodeType.SMART_TAG) are traversed even when isDeep = false and GetChild is invoked for non-markup node type. For example if the first run in a para is wrapped in a StructuredDocumentTag, it will still be returned by GetChild(NodeType.Run, 0, false).

  Parameters:

  nodeType - A NodeType value. Specifies the type of the child node.

  index - Zero based index of the child node to select. Negative indexes are also allowed and indicate access from the end, that is -1 means the last node.

  isDeep - True to select from all child nodes recursively. False to select only among immediate children. See remarks for more info.

  Returns:

  The child node that matches the criteria or null if no matching node is found.

  Example:

  Shows how to apply attributes of a table's style directly to the table's elements.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  Table table = builder.startTable();
  builder.insertCell();
  builder.write("Hello world!");
  builder.endTable();
  
  TableStyle tableStyle = (TableStyle)doc.getStyles().add(StyleType.TABLE, "MyTableStyle1");
  tableStyle.setRowStripe(3);
  tableStyle.setCellSpacing(5.0);
  tableStyle.getShading().setBackgroundPatternColor(Color.WHITE);
  tableStyle.getBorders().setColor(Color.BLUE);
  tableStyle.getBorders().setLineStyle(LineStyle.DOT_DASH);
  
  table.setStyle(tableStyle);
  
  // This method concerns table style attributes such as the ones we set above.
  doc.expandTableStylesToDirectFormatting();
  
  doc.save(getArtifactsDir() + "Document.TableStyleToDirectFormatting.docx");

  Example:

  Shows how to enumerate immediate children of a CompositeNode using the enumerator provided by the ChildNodes collection.

  Document doc = new Document();
  
  Paragraph paragraph = (Paragraph) doc.getChild(NodeType.PARAGRAPH, 0, true);
  paragraph.appendChild(new Run(doc, "Hello world!"));
  paragraph.appendChild(new Run(doc, " Hello again!"));
  
  NodeCollection children = paragraph.getChildNodes();
  
  // Paragraph may contain children of various types such as runs, shapes and so on
  for (Node child : (Iterable<Node>) children)
      if (((child.getNodeType()) == (NodeType.RUN))) {
          Run run = (Run) child;
          System.out.println(run.getText());
      }

• getChildNodes

  public NodeCollection getChildNodes(int nodeType, boolean isDeep)

  Returns a live collection of child nodes that match the specified type.

  The collection of nodes returned by this method is always live.

  A live collection is always in sync with the document. For example, if you selected all sections in a document and enumerate through the collection deleting the sections, the section is removed from the collection immediately when it is removed from the document.

  Parameters:

  nodeType - A NodeType value. Specifies the type of nodes to select.

  isDeep - True to select from all child nodes recursively. False to select only among immediate children.

  Returns:

  A live collection of child nodes of the specified type.

  Example:

  Shows how to print all of a document's comments and their replies.

  Document doc = new Document(getMyDir() + "Comments.docx");
  
  NodeCollection comments = doc.getChildNodes(NodeType.COMMENT, true);
  
  // If a comment has no ancestor, it is a "top-level" comment as opposed to a reply-type comment.
  // Print all top-level comments along with their replies, if there are any.
  for (Comment comment : (Iterable<Comment>) comments)
  {
      if (comment.getAncestor() == null) {
          System.out.println("Top-level comment:");
          System.out.println("\t\"{comment.GetText().Trim()}\", by {comment.Author}");
          System.out.println("Has {comment.Replies.Count} replies");
          for (Comment commentReply : (Iterable<Comment>) comment.getReplies()) {
              System.out.println("\t\"{commentReply.GetText().Trim()}\", by {commentReply.Author}");
          }
          System.out.println();
      }
  }

  Example:

  Shows how to extract images from a document and save them as files.

  Document doc = new Document(getMyDir() + "Images.docx");
  
  NodeCollection shapes = doc.getChildNodes(NodeType.SHAPE, true);
  
  int imageIndex = 0;
  for (Shape shape : (Iterable<Shape>) shapes) {
      if (shape.hasImage()) {
          String imageFileName = MessageFormat.format("File.ExtractImagesToFiles.{0}{1}", imageIndex,
                  FileFormatUtil.imageTypeToExtension(shape.getImageData().getImageType()));
          shape.getImageData().save(getArtifactsDir() + imageFileName);
          imageIndex++;
      }
  }
  
  Assert.assertEquals(9, imageIndex);

• getPageInfo

  public PageInfo getPageInfo(int pageIndex)
                      throws java.lang.Exception

  Gets the page size, orientation and other information about a page that might be useful for printing or rendering.

  Parameters:

  pageIndex - The 0-based page index.

• getText

  public java.lang.String getText()

  Gets the text of this node and of all its children.

  The returned string includes all control and special characters as described in ControlChar.

  Example:

  Shows how to output all paragraphs in a document that are bulleted or numbered.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.getListFormat().applyNumberDefault();
  builder.writeln("Numbered list item 1");
  builder.writeln("Numbered list item 2");
  builder.writeln("Numbered list item 3");
  builder.getListFormat().removeNumbers();
  
  builder.getListFormat().applyBulletDefault();
  builder.writeln("Bulleted list item 1");
  builder.writeln("Bulleted list item 2");
  builder.writeln("Bulleted list item 3");
  builder.getListFormat().removeNumbers();
  
  NodeCollection paras = doc.getChildNodes(NodeType.PARAGRAPH, true);
  for (Paragraph para : (Iterable<Paragraph>) paras) {
      if (para.getListFormat().isListItem()) {
          System.out.println(java.text.MessageFormat.format("*** A paragraph belongs to list {0}", para.getListFormat().getList().getListId()));
          System.out.println(para.getText());
      }
  }

  Example:

  Shows the difference between calling the GetText and ToString methods on a node.

  Document doc = new Document();
  
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.insertField("MERGEFIELD Field");
  
  // GetText will retrieve the visible text as well as field codes and special characters.
  Assert.assertEquals("\u0013MERGEFIELD Field\u0014«Field»\u0015\f", doc.getText());
  
  // ToString will give us the document's appearance if saved to a passed save format.
  Assert.assertEquals("«Field»\r\n", doc.toString(SaveFormat.TEXT));

• importNode

  public Node importNode(Node srcNode, boolean isImportChildren)

  Imports a node from another document to the current document.

  This method uses the ImportFormatMode.USE_DESTINATION_STYLES option to resolve formatting.

  Importing a node creates a copy of the source node belonging to the importing document. The returned node has no parent. The source node is not altered or removed from the original document.

  Before a node from another document can be inserted into this document, it must be imported. During import, document-specific properties such as references to styles and lists are translated from the original to the importing document. After the node was imported, it can be inserted into the appropriate place in the document using insertBefore(com.aspose.words.Node,com.aspose.words.Node) or insertAfter(com.aspose.words.Node,com.aspose.words.Node).

  If the source node already belongs to the destination document, then simply a deep clone of the source node is created.

  Parameters:

  srcNode - The node being imported.

  isImportChildren - True to import all child nodes recursively; otherwise, false.

  Returns:

  The cloned node that belongs to the current document.

  See Also:

  NodeImporter

  Example:

  Shows how to import a node from one document to another.

  Document srcDoc = new Document();
  Document dstDoc = new Document();
  
  srcDoc.getFirstSection().getBody().getFirstParagraph().appendChild(
      new Run(srcDoc, "Source document first paragraph text."));
  dstDoc.getFirstSection().getBody().getFirstParagraph().appendChild(
      new Run(dstDoc, "Destination document first paragraph text."));
  
  // Every node has a parent document, which is the document that contains the node.
  // Inserting a node into a document that the node does not belong to will throw an exception.
  Assert.assertNotEquals(dstDoc, srcDoc.getFirstSection().getDocument());
  Assert.assertThrows(IllegalArgumentException.class, () -> dstDoc.appendChild(srcDoc.getFirstSection()));
  
  // Use the ImportNode method to create a copy of a node, which will have the document
  // that called the ImportNode method set as its new owner document.
  Section importedSection = (Section)dstDoc.importNode(srcDoc.getFirstSection(), true);
  
  Assert.assertEquals(dstDoc, importedSection.getDocument());
  
  // We can now insert the node into the document.
  dstDoc.appendChild(importedSection);
  
  Assert.assertEquals("Destination document first paragraph text.\r\nSource document first paragraph text.\r\n",
      dstDoc.toString(SaveFormat.TEXT));

• importNode

  public Node importNode(Node srcNode, boolean isImportChildren, int importFormatMode)

  Imports a node from another document to the current document with an option to control formatting.

  This overload is useful to control how styles and list formatting are imported.

  Importing a node creates a copy of the source node belonging to the importing document. The returned node has no parent. The source node is not altered or removed from the original document.

  Before a node from another document can be inserted into this document, it must be imported. During import, document-specific properties such as references to styles and lists are translated from the original to the importing document. After the node was imported, it can be inserted into the appropriate place in the document using insertBefore(com.aspose.words.Node,com.aspose.words.Node) or insertAfter(com.aspose.words.Node,com.aspose.words.Node).

  If the source node already belongs to the destination document, then simply a deep clone of the source node is created.

  Parameters:

  srcNode - The node to imported.

  isImportChildren - True to import all child nodes recursively; otherwise, false.

  importFormatMode - A ImportFormatMode value. Specifies how to merge style formatting that clashes.

  Returns:

  The cloned, imported node. The node belongs to the destination document, but has no parent.

  See Also:

  ImportFormatMode, NodeImporter

  Example:

  Shows how to import node from source document to destination document with specific options.

  // Create two documents, and add a character style to each document.
  // Configure the styles to have the same name, but different text formatting.
  Document srcDoc = new Document();
  Style srcStyle = srcDoc.getStyles().add(StyleType.CHARACTER, "My style");
  srcStyle.getFont().setName("Courier New");
  DocumentBuilder srcBuilder = new DocumentBuilder(srcDoc);
  srcBuilder.getFont().setStyle(srcStyle);
  srcBuilder.writeln("Source document text.");
  
  Document dstDoc = new Document();
  Style dstStyle = dstDoc.getStyles().add(StyleType.CHARACTER, "My style");
  dstStyle.getFont().setName("Calibri");
  DocumentBuilder dstBuilder = new DocumentBuilder(dstDoc);
  dstBuilder.getFont().setStyle(dstStyle);
  dstBuilder.writeln("Destination document text.");
  
  // Import the Section from the destination document into the source document, causing a style name collision.
  // If we use destination styles, then the imported source text with the same style name
  // as destination text will adopt the destination style.
  Section importedSection = (Section)dstDoc.importNode(srcDoc.getFirstSection(), true, ImportFormatMode.USE_DESTINATION_STYLES);
  Assert.assertEquals(dstStyle.getFont().getName(), importedSection.getBody().getFirstParagraph().getRuns().get(0).getFont().getName());
  Assert.assertEquals(dstStyle.getName(), importedSection.getBody().getFirstParagraph().getRuns().get(0).getFont().getStyleName());
  
  // If we use ImportFormatMode.KeepDifferentStyles, the source style is preserved,
  // and the naming clash resolves by adding a suffix.
  dstDoc.importNode(srcDoc.getFirstSection(), true, ImportFormatMode.KEEP_DIFFERENT_STYLES);
  Assert.assertEquals(dstStyle.getFont().getName(), dstDoc.getStyles().get("My style").getFont().getName());
  Assert.assertEquals(srcStyle.getFont().getName(), dstDoc.getStyles().get("My style_0").getFont().getName());

• indexOf

  public int indexOf(Node child)

  Returns the index of the specified child node in the child node array.

  Returns -1 if the node is not found in the child nodes.

  Example:

  Shows how to get the index of a given child node from its parent.

  Document doc = new Document(getMyDir() + "Rendering.docx");
  
  // Get the body of the first section in the document
  Body body = doc.getFirstSection().getBody();
  
  // Retrieve the index of the last paragraph in the body
  Assert.assertEquals(24, body.getChildNodes().indexOf(body.getLastParagraph()));

• insertAfter

  public Node insertAfter(Node newChild, Node refChild)

  Inserts the specified node immediately after the specified reference node.

  If refChild is null, inserts newChild at the beginning of the list of child nodes.

  If the newChild is already in the tree, it is first removed.

  If the node being inserted was created from another document, you should use importNode(com.aspose.words.Node,boolean,int) to import the node to the current document. The imported node can then be inserted into the current document.

  Parameters:

  newChild - The Node to insert.

  refChild - The Node that is the reference node. The newNode is placed after the refNode.

  Returns:

  The inserted node.

  Example:

  Shows how to replace all textboxes with images.

  Document doc = new Document(getMyDir() + "Textboxes in drawing canvas.docx");
  
  // This gets a live collection of all shape nodes in the document
  NodeCollection shapeCollection = doc.getChildNodes(NodeType.SHAPE, true);
  
  // Since we will be adding/removing nodes, it is better to copy all collection
  // into a fixed size array, otherwise iterator will be invalidated
  Node[] shapes = shapeCollection.toArray();
  
  for (Node node : shapes) {
      Shape shape = (Shape) node;
      // Filter out all shapes that we don't need
      if (shape.getShapeType() == ShapeType.TEXT_BOX) {
          // Create a new shape that will replace the existing shape
          Shape image = new Shape(doc, ShapeType.IMAGE);
  
          // Load the image into the new shape
          image.getImageData().setImage(getImageDir() + "Windows MetaFile.wmf");
  
          // Make new shape's position to match the old shape
          image.setLeft(shape.getLeft());
          image.setTop(shape.getTop());
          image.setWidth(shape.getWidth());
          image.setHeight(shape.getHeight());
          image.setRelativeHorizontalPosition(shape.getRelativeHorizontalPosition());
          image.setRelativeVerticalPosition(shape.getRelativeVerticalPosition());
          image.setHorizontalAlignment(shape.getHorizontalAlignment());
          image.setVerticalAlignment(shape.getVerticalAlignment());
          image.setWrapType(shape.getWrapType());
          image.setWrapSide(shape.getWrapSide());
  
          // Insert new shape after the old shape and remove the old shape
          shape.getParentNode().insertAfter(image, shape);
          shape.remove();
      }
  }
  
  doc.save(getArtifactsDir() + "Shape.ReplaceTextboxesWithImages.docx");

  Example:

  Shows how to add, update and delete child nodes from a CompositeNode's child collection.

  Document doc = new Document();
  
  // An empty document has one paragraph by default
  Assert.assertEquals(1, doc.getFirstSection().getBody().getParagraphs().getCount());
  
  // A paragraph is a composite node because it can contain runs, which are another type of node
  Paragraph paragraph = doc.getFirstSection().getBody().getFirstParagraph();
  Run paragraphText = new Run(doc, "Initial text. ");
  paragraph.appendChild(paragraphText);
  
  // We will place these 3 children into the main text of our paragraph
  Run run1 = new Run(doc, "Run 1. ");
  Run run2 = new Run(doc, "Run 2. ");
  Run run3 = new Run(doc, "Run 3. ");
  
  // We initialized them but not in our paragraph yet
  Assert.assertEquals("Initial text.", paragraph.getText().trim());
  
  // Insert run2 before initial paragraph text. This will be at the start of the paragraph
  paragraph.insertBefore(run2, paragraphText);
  
  // Insert run3 after initial paragraph text. This will be at the end of the paragraph
  paragraph.insertAfter(run3, paragraphText);
  
  // Insert run1 before every other child node. run2 was the start of the paragraph, now it will be run1
  paragraph.prependChild(run1);
  
  Assert.assertEquals("Run 1. Run 2. Initial text. Run 3.", paragraph.getText().trim());
  Assert.assertEquals(4, paragraph.getChildNodes(NodeType.ANY, true).getCount());
  
  // Access the child node collection and update/delete children
  ((Run) paragraph.getChildNodes(NodeType.RUN, true).get(1)).setText("Updated run 2. ");
  paragraph.getChildNodes(NodeType.RUN, true).remove(paragraphText);
  
  Assert.assertEquals("Run 1. Updated run 2. Run 3.", paragraph.getText().trim());
  Assert.assertEquals(3, paragraph.getChildNodes(NodeType.ANY, true).getCount());

• insertBefore

  public Node insertBefore(Node newChild, Node refChild)

  Inserts the specified node immediately before the specified reference node.

  If refChild is null, inserts newChild at the end of the list of child nodes.

  If the newChild is already in the tree, it is first removed.

  If the node being inserted was created from another document, you should use importNode(com.aspose.words.Node,boolean,int) to import the node to the current document. The imported node can then be inserted into the current document.

  Parameters:

  newChild - The Node to insert.

  refChild - The Node that is the reference node. The newChild is placed before this node.

  Returns:

  The inserted node.

  Example:

  Shows how to add, update and delete child nodes from a CompositeNode's child collection.

  Document doc = new Document();
  
  // An empty document has one paragraph by default
  Assert.assertEquals(1, doc.getFirstSection().getBody().getParagraphs().getCount());
  
  // A paragraph is a composite node because it can contain runs, which are another type of node
  Paragraph paragraph = doc.getFirstSection().getBody().getFirstParagraph();
  Run paragraphText = new Run(doc, "Initial text. ");
  paragraph.appendChild(paragraphText);
  
  // We will place these 3 children into the main text of our paragraph
  Run run1 = new Run(doc, "Run 1. ");
  Run run2 = new Run(doc, "Run 2. ");
  Run run3 = new Run(doc, "Run 3. ");
  
  // We initialized them but not in our paragraph yet
  Assert.assertEquals("Initial text.", paragraph.getText().trim());
  
  // Insert run2 before initial paragraph text. This will be at the start of the paragraph
  paragraph.insertBefore(run2, paragraphText);
  
  // Insert run3 after initial paragraph text. This will be at the end of the paragraph
  paragraph.insertAfter(run3, paragraphText);
  
  // Insert run1 before every other child node. run2 was the start of the paragraph, now it will be run1
  paragraph.prependChild(run1);
  
  Assert.assertEquals("Run 1. Run 2. Initial text. Run 3.", paragraph.getText().trim());
  Assert.assertEquals(4, paragraph.getChildNodes(NodeType.ANY, true).getCount());
  
  // Access the child node collection and update/delete children
  ((Run) paragraph.getChildNodes(NodeType.RUN, true).get(1)).setText("Updated run 2. ");
  paragraph.getChildNodes(NodeType.RUN, true).remove(paragraphText);
  
  Assert.assertEquals("Run 1. Updated run 2. Run 3.", paragraph.getText().trim());
  Assert.assertEquals(3, paragraph.getChildNodes(NodeType.ANY, true).getCount());

• iterator

  public java.util.Iterator<Node> iterator()

  Provides support for the for each style iteration over the child nodes of this node.

  Example:

  Shows how to enumerate immediate children of a CompositeNode using the enumerator provided by the ChildNodes collection.

  Document doc = new Document();
  
  Paragraph paragraph = (Paragraph) doc.getChild(NodeType.PARAGRAPH, 0, true);
  paragraph.appendChild(new Run(doc, "Hello world!"));
  paragraph.appendChild(new Run(doc, " Hello again!"));
  
  NodeCollection children = paragraph.getChildNodes();
  
  // Paragraph may contain children of various types such as runs, shapes and so on
  for (Node child : (Iterable<Node>) children)
      if (((child.getNodeType()) == (NodeType.RUN))) {
          Run run = (Run) child;
          System.out.println(run.getText());
      }

• joinRunsWithSameFormatting

  public int joinRunsWithSameFormatting()

  Joins runs with same formatting in all paragraphs of the document.

  This is an optimization method. Some documents contain adjacent runs with same formatting. Usually this occurs if a document was intensively edited manually. You can reduce the document size and speed up further processing by joining these runs.

  The operation checks every Paragraph node in the document for adjacent Run nodes having identical properties. It ignores unique identifiers used to track editing sessions of run creation and modification. First run in every joining sequence accumulates all text. Remaining runs are deleted from the document.

  Returns:

  Number of joins performed. When N adjacent runs are being joined they count as N - 1 joins.

  Example:

  Shows how to join runs in a document to reduce unneeded runs.

  // Open a document that contains adjacent runs of text with identical formatting,
  // which commonly occurs if we edit the same paragraph multiple times in Microsoft Word.
  Document doc = new Document(getMyDir() + "Rendering.docx");
  
  // If any number of these runs are adjacent with identical formatting,
  // then the document may be simplified.
  Assert.assertEquals(317, doc.getChildNodes(NodeType.RUN, true).getCount());
  
  // Combine such runs with this method, and verify the number of run joins that will take place.
  Assert.assertEquals(121, doc.joinRunsWithSameFormatting());
  
  // The number of joins and the number of runs we have after the join
  // should add up the number of runs we had initially.
  Assert.assertEquals(196, doc.getChildNodes(NodeType.RUN, true).getCount());

• nextPreOrder

  public Node nextPreOrder(Node rootNode)

  Gets next node according to the pre-order tree traversal algorithm.

  Parameters:

  rootNode - The top node (limit) of traversal.

  Returns:

  Next node in pre-order order. Null if reached the rootNode.

  Example:

  Shows how to delete all images from a document using pre-order tree traversal.

  Document doc = new Document(getMyDir() + "Images.docx");
  Assert.assertEquals(doc.getChildNodes(NodeType.SHAPE, true).getCount(), 10);
  
  Node curNode = doc;
  while (curNode != null) {
      Node nextNode = curNode.nextPreOrder(doc);
  
      if (curNode.previousPreOrder(doc) != null && nextNode != null) {
          Assert.assertEquals(curNode, nextNode.previousPreOrder(doc));
      }
  
      if (curNode.getNodeType() == NodeType.SHAPE) {
          Shape shape = (Shape) curNode;
  
          // Several shape types can have an image including image shapes and OLE objects
          if (shape.hasImage()) {
              shape.remove();
          }
      }
  
      curNode = nextNode;
  }
  
  // The only remaining shape doesn't have an image
  Assert.assertEquals(1, doc.getChildNodes(NodeType.SHAPE, true).getCount());
  Assert.assertFalse(((Shape) doc.getChild(NodeType.SHAPE, 0, true)).hasImage());

• normalizeFieldTypes

  public void normalizeFieldTypes()

  Changes field type values FieldChar.FieldType of FieldStart, FieldSeparator, FieldEnd in the whole document so that they correspond to the field types contained in the field codes.

  Use this method after document changes that affect field types.

  To change field type values in a specific part of the document use Range.normalizeFieldTypes().

  Example:

  Shows how to get the keep a field's type up to date with its field code.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  Field field = builder.insertField("DATE", null);
  
  // Aspose.Words automatically detects field types based on field codes.
  Assert.assertEquals(FieldType.FIELD_DATE, field.getType());
  
  // Manually change the raw text of the field, which determines the field code.
  Run fieldText = (Run)doc.getFirstSection().getBody().getFirstParagraph().getChildNodes(NodeType.RUN, true).get(0);
  fieldText.setText("PAGE");
  
  // Changing the field code has changed this field to one of a different type,
  // but the field's type attributes still display the old type.
  Assert.assertEquals("PAGE", field.getFieldCode());
  Assert.assertEquals(FieldType.FIELD_DATE, field.getType());
  Assert.assertEquals(FieldType.FIELD_DATE, field.getStart().getFieldType());
  Assert.assertEquals(FieldType.FIELD_DATE, field.getSeparator().getFieldType());
  Assert.assertEquals(FieldType.FIELD_DATE, field.getEnd().getFieldType());
  
  // Update those attributes with this method to display current value.
  doc.normalizeFieldTypes();
  
  Assert.assertEquals(FieldType.FIELD_PAGE, field.getType());
  Assert.assertEquals(FieldType.FIELD_PAGE, field.getStart().getFieldType());
  Assert.assertEquals(FieldType.FIELD_PAGE, field.getSeparator().getFieldType()); 
  Assert.assertEquals(FieldType.FIELD_PAGE, field.getEnd().getFieldType());

• prependChild

  public Node prependChild(Node newChild)

  Adds the specified node to the beginning of the list of child nodes for this node.

  If the newChild is already in the tree, it is first removed.

  If the node being inserted was created from another document, you should use importNode(com.aspose.words.Node,boolean,int) to import the node to the current document. The imported node can then be inserted into the current document.

  Parameters:

  newChild - The node to add.

  Returns:

  The node added.

  Example:

  Shows how to add, update and delete child nodes from a CompositeNode's child collection.

  Document doc = new Document();
  
  // An empty document has one paragraph by default
  Assert.assertEquals(1, doc.getFirstSection().getBody().getParagraphs().getCount());
  
  // A paragraph is a composite node because it can contain runs, which are another type of node
  Paragraph paragraph = doc.getFirstSection().getBody().getFirstParagraph();
  Run paragraphText = new Run(doc, "Initial text. ");
  paragraph.appendChild(paragraphText);
  
  // We will place these 3 children into the main text of our paragraph
  Run run1 = new Run(doc, "Run 1. ");
  Run run2 = new Run(doc, "Run 2. ");
  Run run3 = new Run(doc, "Run 3. ");
  
  // We initialized them but not in our paragraph yet
  Assert.assertEquals("Initial text.", paragraph.getText().trim());
  
  // Insert run2 before initial paragraph text. This will be at the start of the paragraph
  paragraph.insertBefore(run2, paragraphText);
  
  // Insert run3 after initial paragraph text. This will be at the end of the paragraph
  paragraph.insertAfter(run3, paragraphText);
  
  // Insert run1 before every other child node. run2 was the start of the paragraph, now it will be run1
  paragraph.prependChild(run1);
  
  Assert.assertEquals("Run 1. Run 2. Initial text. Run 3.", paragraph.getText().trim());
  Assert.assertEquals(4, paragraph.getChildNodes(NodeType.ANY, true).getCount());
  
  // Access the child node collection and update/delete children
  ((Run) paragraph.getChildNodes(NodeType.RUN, true).get(1)).setText("Updated run 2. ");
  paragraph.getChildNodes(NodeType.RUN, true).remove(paragraphText);
  
  Assert.assertEquals("Run 1. Updated run 2. Run 3.", paragraph.getText().trim());
  Assert.assertEquals(3, paragraph.getChildNodes(NodeType.ANY, true).getCount());

• previousPreOrder

  public Node previousPreOrder(Node rootNode)

  Gets the previous node according to the pre-order tree traversal algorithm.

  Parameters:

  rootNode - The top node (limit) of traversal.

  Returns:

  Previous node in pre-order order. Null if reached the rootNode.

  Example:

  Shows how to delete all images from a document using pre-order tree traversal.

  Document doc = new Document(getMyDir() + "Images.docx");
  Assert.assertEquals(doc.getChildNodes(NodeType.SHAPE, true).getCount(), 10);
  
  Node curNode = doc;
  while (curNode != null) {
      Node nextNode = curNode.nextPreOrder(doc);
  
      if (curNode.previousPreOrder(doc) != null && nextNode != null) {
          Assert.assertEquals(curNode, nextNode.previousPreOrder(doc));
      }
  
      if (curNode.getNodeType() == NodeType.SHAPE) {
          Shape shape = (Shape) curNode;
  
          // Several shape types can have an image including image shapes and OLE objects
          if (shape.hasImage()) {
              shape.remove();
          }
      }
  
      curNode = nextNode;
  }
  
  // The only remaining shape doesn't have an image
  Assert.assertEquals(1, doc.getChildNodes(NodeType.SHAPE, true).getCount());
  Assert.assertFalse(((Shape) doc.getChild(NodeType.SHAPE, 0, true)).hasImage());

• print

  public void print()

  Prints the whole document to the default printer.

  Example:

  Prints the whole document to the default printer.

  Document doc = new Document(getMyDir() + "Document.docx");
  doc.print();

• print

  public void print(java.lang.String printerName)

  Print the whole document to the specified printer, using the standard (no User Interface) print controller.

  Parameters:

  printerName - The name of the printer.

  Example:

  Prints the whole document to a specified printer.

  Document doc = new Document(getMyDir() + "Document.docx");
  doc.print("KONICA MINOLTA magicolor 2400W");

• print

  public void print(javax.print.attribute.AttributeSet printerSettings)

  Prints the document according to the specified printer settings, using the standard (no User Interface) print controller.

  The javax.print.attribute.AttributeSet object allows you to specify the printer to print on, the range of pages of to print and other options.

  The javax.print.attribute.AttributeSet can contain both javax.print.attribute.PrintRequestAttribute to configure PrintJob request and javax.print.attribute.PrintServiceAttribute to configure PrintService lookup.

  Parameters:

  printerSettings - The printer settings to use.

  Example:

  Prints a range of pages.

  Document doc = new Document(getMyDir() + "Rendering.docx");
  
  PrintRequestAttributeSet printAttribute = new HashPrintRequestAttributeSet();
  printAttribute.add(new PageRanges(1, 3));
  
  doc.print(printAttribute);

• print

  public void print(javax.print.attribute.AttributeSet printerSettings, java.lang.String documentName)

  Prints the document according to the specified printer settings, using the standard (no User Interface) print controller and a document name.

  The javax.print.attribute.AttributeSet object allows you to specify the printer to print on, the range of pages of to print and other options.

  The javax.print.attribute.AttributeSet can contain both javax.print.attribute.PrintRequestAttribute to configure PrintJob request and javax.print.attribute.PrintServiceAttribute to configure PrintService lookup.

  Parameters:

  printerSettings - The printer settings to use.

  documentName - The document name to display (for example, in a print status dialog box or printer queue) while printing the document.

  Example:

  Prints a range of pages along with the name of the document.

  Document doc = new Document(getMyDir() + "Rendering.docx");
  
  PrintRequestAttributeSet printAttribute = new HashPrintRequestAttributeSet();
  printAttribute.add(new PageRanges(1, 3));
  
  doc.print(printAttribute, "Rendering.PrintRangeWithDocumentName.docx");

• protect

  public void protect(int type)

  Protects the document from changes without changing the existing password or assigns a random password.

  When a document is protected, the user can make only limited changes, such as adding annotations, making revisions, or completing a form.

  When you protect a document, and the document already has a protection password, the existing protection password is not changed.

  When you protect a document, and the document does not have a protection password, this method assigns a random password that makes it impossible to unprotect the document in Microsoft Word, but you still can unprotect the document in Aspose.Words as it does not require a password when unprotecting.

  Parameters:

  type - A ProtectionType value. Specifies the protection type for the document.

  Example:

  Shows how to protect a section so only editing in form fields is possible.

  Document doc = new Document();
  
  // Insert two sections with some text
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.writeln("Section 1. Unprotected.");
  builder.insertBreak(BreakType.SECTION_BREAK_CONTINUOUS);
  builder.writeln("Section 2. Protected.");
  
  // Section protection only works when document protection is turned and only editing in form fields is allowed
  doc.protect(ProtectionType.ALLOW_ONLY_FORM_FIELDS);
  
  // By default, all sections are protected, but we can selectively turn protection off
  doc.getSections().get(0).setProtectedForForms(false);
  
  doc.save(getArtifactsDir() + "Section.Protect.docx");

• protect

  public void protect(int type, java.lang.String password)

  Protects the document from changes and optionally sets a protection password.

  When a document is protected, the user can make only limited changes, such as adding annotations, making revisions, or completing a form.

  Note that document protection is different from write protection. Write protection is specified using the WriteProtection.

  Parameters:

  type - A ProtectionType value. Specifies the protection type for the document.

  password - The password to protect the document with. Specify null or empty string if you want to protect the document without a password.

  Example:

  Shows how to protect and unprotect a document.

  Document doc = new Document();
  doc.protect(ProtectionType.READ_ONLY, "password");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, doc.getProtectionType());
  
  // If we open this document with Microsoft Word intending to edit it,
  // we will need to apply the password to get through the protection.
  doc.save(getArtifactsDir() + "Document.Protect.docx");
  
  // Note that the protection only applies to Microsoft Word users opening our document.
  // We have not encrypted the document in any way, and we do not need the password to open and edit it programmatically.
  Document protectedDoc = new Document(getArtifactsDir() + "Document.Protect.docx");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, protectedDoc.getProtectionType());
  
  DocumentBuilder builder = new DocumentBuilder(protectedDoc);
  builder.writeln("Text added to a protected document.");
  
  // There are two ways of removing protection from a document.
  // 1 - With no password:
  doc.unprotect();
  
  Assert.assertEquals(ProtectionType.NO_PROTECTION, doc.getProtectionType());
  
  doc.protect(ProtectionType.READ_ONLY, "NewPassword");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, doc.getProtectionType());
  
  doc.unprotect("WrongPassword");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, doc.getProtectionType());
  
  // 2 - With the correct password:
  doc.unprotect("NewPassword");
  
  Assert.assertEquals(ProtectionType.NO_PROTECTION, doc.getProtectionType());

• remove

  @Deprecated
  public void remove()

  Deprecated. Reserved for internal use.

• removeAllChildren

  public void removeAllChildren()

  Removes all the child nodes of the current node.

  Example:

  Shows how to construct an Aspose Words document node by node.

  Document doc = new Document();
  
  // A newly created blank document still comes one section, one body and one paragraph
  // Calling this method will remove all those nodes to completely empty the document
  doc.removeAllChildren();
  
  // This document now has no composite nodes that content can be added to
  // If we wish to edit it, we will need to repopulate its node collection,
  // which we will start to do with by creating a new Section node
  Section section = new Section(doc);
  
  // Append the section to the document
  doc.appendChild(section);
  
  // Lets set some properties for the section
  section.getPageSetup().setSectionStart(SectionStart.NEW_PAGE);
  section.getPageSetup().setPaperSize(PaperSize.LETTER);
  
  // A section needs a body, which will contain all other nodes that can be edited
  Body body = new Body(doc);
  section.appendChild(body);
  
  // The body needs to have at least one paragraph
  // Note that the paragraph has not yet been added to the document, but we have to specify the parent document
  // The parent document is needed so the paragraph can correctly work
  // with styles and other document-wide information
  Paragraph para = new Paragraph(doc);
  body.appendChild(para);
  
  // We can set some formatting for the paragraph
  para.getParagraphFormat().setStyleName("Heading 1");
  para.getParagraphFormat().setAlignment(ParagraphAlignment.CENTER);
  
  // Now we can begin adding content to the document
  Run run = new Run(doc);
  run.setText("Hello World!");
  run.getFont().setColor(Color.RED);
  para.appendChild(run);
  
  Assert.assertEquals("Hello World!" + ControlChar.SECTION_BREAK_CHAR, doc.getText());
  
  doc.save(getArtifactsDir() + "Section.CreateFromScratch.docx");

• removeChild

  public Node removeChild(Node oldChild)

  Removes the specified child node.

  The parent of oldChild is set to null after the node is removed.

  Parameters:

  oldChild - The node to remove.

  Returns:

  The removed node.

  Example:

  Shows how to use of methods of Node and CompositeNode to remove a section before the last section in the document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Create a second section by inserting a section break and add text to both sections
  builder.writeln("Section 1 text.");
  builder.insertBreak(BreakType.SECTION_BREAK_CONTINUOUS);
  builder.writeln("Section 2 text.");
  
  // Both sections are siblings of each other
  Section lastSection = (Section) doc.getLastChild();
  Section firstSection = (Section) lastSection.getPreviousSibling();
  
  // Remove a section based on its sibling relationship with another section
  if (lastSection.getPreviousSibling() != null)
      doc.removeChild(firstSection);
  
  // The section we removed was the first one, leaving the document with only the second
  Assert.assertEquals("Section 2 text.", doc.getText().trim());

• removeExternalSchemaReferences

  public void removeExternalSchemaReferences()

  Removes external XML schema references from this document.

  Example:

  Shows how to remove all external XML schema references from a document.

  Document doc = new Document(getMyDir() + "External XML schema.docx");
  
  doc.removeExternalSchemaReferences();

• removeMacros

  public void removeMacros()

  Removes all macros (the VBA project) as well as toolbars and command customizations from the document.

  By removing all macros from a document you can ensure the document contains no macro viruses.

  Example:

  Shows how to remove all macros from a document.

  Document doc = new Document(getMyDir() + "Macro.docm");
  
  Assert.assertTrue(doc.hasMacros());
  Assert.assertEquals("Project", doc.getVbaProject().getName());
  
  // Remove the document's VBA project, along with all of its macros.
  doc.removeMacros();
  
  Assert.assertFalse(doc.hasMacros());
  Assert.assertNull(doc.getVbaProject());

• removeSmartTags

  public void removeSmartTags()

  Removes all SmartTag descendant nodes of the current node.

  This method does not remove the content of the smart tags.

  Example:

  Removes all smart tags from descendant nodes of the composite node.

  Document doc = new Document(getMyDir() + "Smart tags.doc");
  Assert.assertEquals(8, doc.getChildNodes(NodeType.SMART_TAG, true).getCount());
  
  // Remove smart tags from the whole document
  doc.removeSmartTags();
  
  Assert.assertEquals(0, doc.getChildNodes(NodeType.SMART_TAG, true).getCount());

• renderToScale

  public java.awt.geom.Point2D.Float renderToScale(int pageIndex, java.awt.Graphics2D graphics, float x, float y, float scale)
                     throws java.lang.Exception

  Renders a document page into a java.awt.Graphics2D object to a specified scale.

  Parameters:

  pageIndex - The 0-based page index.

  graphics - The object where to render to.

  x - The X coordinate (in world units) of the top left corner of the rendered page.

  y - The Y coordinate (in world units) of the top left corner of the rendered page.

  scale - The scale for rendering the page (1.0 is 100%).

  Returns:

  The width and height (in world units) of the rendered page.

  Example:

  Renders individual pages to graphics to create one image with thumbnails of all pages.

  // The user opens or builds a document
  Document doc = new Document(getMyDir() + "Rendering.docx");
  
  // This defines the number of columns to display the thumbnails in
  final int thumbColumns = 2;
  
  // Calculate the required number of rows for thumbnails
  // We can now get the number of pages in the document
  int thumbRows = doc.getPageCount() / thumbColumns;
  int remainder = doc.getPageCount() % thumbColumns;
  
  if (remainder > 0) thumbRows++;
  
  // Lets say I want thumbnails to be of this zoom
  float scale = 0.25f;
  
  // For simplicity lets pretend all pages in the document are of the same size,
  // so we can use the size of the first page to calculate the size of the thumbnail
  Dimension thumbSize = doc.getPageInfo(0).getSizeInPixels(scale, 96);
  
  // Calculate the size of the image that will contain all the thumbnails
  int imgWidth = (int) (thumbSize.getWidth() * thumbColumns);
  int imgHeight = (int) (thumbSize.getHeight() * thumbRows);
  
  BufferedImage img = new BufferedImage(imgWidth, imgHeight, BufferedImage.TYPE_INT_ARGB);
  // The user has to provides a Graphics object to draw on
  // The Graphics object can be created from a bitmap, from a metafile, printer or window
  Graphics2D gr = img.createGraphics();
  try {
      gr.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING, RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
  
      gr.setColor(Color.white);
      // Fill the "paper" with white, otherwise it will be transparent
      gr.fillRect(0, 0, imgWidth, imgHeight);
  
      for (int pageIndex = 0; pageIndex < doc.getPageCount(); pageIndex++) {
          int rowIdx = pageIndex / thumbColumns;
          int columnIdx = pageIndex % thumbColumns;
  
          // Specify where we want the thumbnail to appear
          float thumbLeft = (float) (columnIdx * thumbSize.getWidth());
          float thumbTop = (float) (rowIdx * thumbSize.getHeight());
  
          Point2D.Float size = doc.renderToScale(pageIndex, gr, thumbLeft, thumbTop, scale);
  
          gr.setColor(Color.black);
  
          // Draw the page rectangle
          gr.drawRect((int) thumbLeft, (int) thumbTop, (int) size.getX(), (int) size.getY());
      }
  
      ImageIO.write(img, "PNG", new File(getArtifactsDir() + "Rendering.Thumbnails.png"));
  } finally {
      if (gr != null) {
          gr.dispose();
      }
  }

• renderToSize

  public float renderToSize(int pageIndex, java.awt.Graphics2D graphics, float x, float y, float width, float height)
                    throws java.lang.Exception

  Renders a document page into a java.awt.Graphics2D object to a specified size.

  Parameters:

  pageIndex - The 0-based page index.

  graphics - The object where to render to.

  x - The X coordinate (in world units) of the top left corner of the rendered page.

  y - The Y coordinate (in world units) of the top left corner of the rendered page.

  width - The maximum width (in world units) that can be occupied by the rendered page.

  height - The maximum height (in world units) that can be occupied by the rendered page.

  Returns:

  The scale that was automatically calculated for the rendered page to fit the specified size.

  Example:

  Render to a BufferedImage at a specified location and size.

  Document doc = new Document(getMyDir() + "Rendering.docx");
  
  BufferedImage img = new BufferedImage(700, 700, BufferedImage.TYPE_INT_ARGB);
  // User has some sort of a Graphics object
  // In this case created from a bitmap
  Graphics2D gr = img.createGraphics();
  try {
      // The user can specify any options on the Graphics object including
      // transform, antialiasing, page units, etc
      gr.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING, RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
  
      // The output should be offset 0.5" from the edge and rotated
      gr.translate(ConvertUtil.inchToPoint(0.5f), ConvertUtil.inchToPoint(0.5f));
      gr.rotate(10.0 * Math.PI / 180.0, img.getWidth() / 2.0, img.getHeight() / 2.0);
  
      // Set pen color and draw our test rectangle
      gr.setColor(Color.RED);
      gr.drawRect(0, 0, (int) ConvertUtil.inchToPoint(3), (int) ConvertUtil.inchToPoint(3));
  
      // User specifies (in world coordinates) where on the Graphics to render and what size
      float returnedScale = doc.renderToSize(0, gr, 0f, 0f, (float) ConvertUtil.inchToPoint(3), (float) ConvertUtil.inchToPoint(3));
  
      // This is the calculated scale factor to fit 297mm into 3"
      System.out.println(MessageFormat.format("The image was rendered at {0,number,#}% zoom.", returnedScale * 100));
  
      ImageIO.write(img, "PNG", new File(getArtifactsDir() + "Rendering.RenderToSize.png"));
  } finally {
      if (gr != null) {
          gr.dispose();
      }
  }

• save

  public void save(java.io.OutputStream outputStream, SaveOptions saveOptions)
           throws java.lang.Exception

  Saves the document to a stream using the specified save options.

  Parameters:

  stream - Stream where to save the document.

  saveOptions - Specifies the options that control how the document is saved. Can be null. If this is null, the document will be saved in the binary DOC format.

  Returns:

  Additional information that you can optionally use.

  Example:

  Converts just one page (third page in this example) of the document to PDF.

  Document doc = new Document(getMyDir() + "Rendering.docx");
  
  OutputStream stream = new FileOutputStream(getArtifactsDir() + "Rendering.SaveToPdfStreamOnePage.pdf");
  try {
      PdfSaveOptions options = new PdfSaveOptions();
      options.setPageIndex(2);
      options.setPageCount(1);
      doc.save(stream, options);
  } finally {
      if (stream != null) {
          stream.close();
      }
  }

• save

  public void save(java.io.OutputStream outputStream, int saveFormat)
           throws java.lang.Exception

  Saves the document to a stream using the specified format.

  Parameters:

  stream - Stream where to save the document.

  saveFormat - The format in which to save the document.

  Returns:

  Additional information that you can optionally use.

  Example:

  Shows how to save a document to the JPEG format using the Save method and the ImageSaveOptions class.

  // Open the document
  Document doc = new Document(getMyDir() + "Rendering.docx");
  // Save as a JPEG image file with default options
  doc.save(getArtifactsDir() + "Rendering.SaveAsImage.DefaultJpgOptions.jpg");
  
  // Save document to an ByteArrayOutputStream as a JPEG with default options
  ByteArrayOutputStream docStream = new ByteArrayOutputStream();
  doc.save(docStream, SaveFormat.JPEG);
  
  // Save document to a JPEG image with specified options
  // Render the third page only and set the JPEG quality to 80%
  // In this case we need to pass the desired SaveFormat to the ImageSaveOptions constructor 
  // to signal what type of image to save as
  ImageSaveOptions imageOptions = new ImageSaveOptions(SaveFormat.JPEG);
  imageOptions.setPageIndex(2);
  imageOptions.setPageCount(1);
  imageOptions.setJpegQuality(80);
  doc.save(getArtifactsDir() + "Rendering.SaveAsImage.CustomJpgOptions.jpg", imageOptions);

  Example:

  Shows how to save a document to a stream.

  Document doc = new Document(getMyDir() + "Document.docx");
  
  ByteArrayOutputStream dstStream = new ByteArrayOutputStream();
  try {
      doc.save(dstStream, SaveFormat.DOCX);
  
      byte[] dataBytes = dstStream.toByteArray();
      ByteArrayInputStream byteStream = new ByteArrayInputStream(dataBytes);
  
      // Verify that the stream contains the document.
      Assert.assertEquals("Hello World!\\r\\rHello Word!\\r\\r\\rHello World!", new Document(byteStream).getText().trim());
  } finally {
      if (dstStream != null) dstStream.close();
  }

  Example:

  Saves a document page as a BMP image into a ByteArayOutputStream.

  Document doc = new Document(getMyDir() + "Rendering.docx");
  
  ByteArrayOutputStream stream = new ByteArrayOutputStream();
  doc.save(stream, SaveFormat.BMP);
  
  // The stream now contains image bytes
  byte[] imageBytes = stream.toByteArray();
  
  // Read the bytes back into an image
  BufferedImage image = ImageIO.read(new ByteArrayInputStream(imageBytes));

• save

  public SaveOutputParameters save(java.lang.String fileName)
                           throws java.lang.Exception

  Saves the document to a file. Automatically determines the save format from the extension.

  Parameters:

  fileName - The name for the document. If a document with the specified file name already exists, the existing document is overwritten.

  Returns:

  Additional information that you can optionally use.

  Example:

  Shows how to save a document to the JPEG format using the Save method and the ImageSaveOptions class.

  // Open the document
  Document doc = new Document(getMyDir() + "Rendering.docx");
  // Save as a JPEG image file with default options
  doc.save(getArtifactsDir() + "Rendering.SaveAsImage.DefaultJpgOptions.jpg");
  
  // Save document to an ByteArrayOutputStream as a JPEG with default options
  ByteArrayOutputStream docStream = new ByteArrayOutputStream();
  doc.save(docStream, SaveFormat.JPEG);
  
  // Save document to a JPEG image with specified options
  // Render the third page only and set the JPEG quality to 80%
  // In this case we need to pass the desired SaveFormat to the ImageSaveOptions constructor 
  // to signal what type of image to save as
  ImageSaveOptions imageOptions = new ImageSaveOptions(SaveFormat.JPEG);
  imageOptions.setPageIndex(2);
  imageOptions.setPageCount(1);
  imageOptions.setJpegQuality(80);
  doc.save(getArtifactsDir() + "Rendering.SaveAsImage.CustomJpgOptions.jpg", imageOptions);

  Example:

  Shows how to open a document and convert it to .PDF.

  Document doc = new Document(getMyDir() + "Document.docx");
  
  doc.save(getArtifactsDir() + "Document.ConvertToPdf.pdf");

• save

  public SaveOutputParameters save(java.lang.String fileName, SaveOptions saveOptions)
                           throws java.lang.Exception

  Saves the document to a file using the specified save options.

  Parameters:

  fileName - The name for the document. If a document with the specified file name already exists, the existing document is overwritten.

  saveOptions - Specifies the options that control how the document is saved. Can be null.

  Returns:

  Additional information that you can optionally use.

  Example:

  Shows how to save a document to the JPEG format using the Save method and the ImageSaveOptions class.

  // Open the document
  Document doc = new Document(getMyDir() + "Rendering.docx");
  // Save as a JPEG image file with default options
  doc.save(getArtifactsDir() + "Rendering.SaveAsImage.DefaultJpgOptions.jpg");
  
  // Save document to an ByteArrayOutputStream as a JPEG with default options
  ByteArrayOutputStream docStream = new ByteArrayOutputStream();
  doc.save(docStream, SaveFormat.JPEG);
  
  // Save document to a JPEG image with specified options
  // Render the third page only and set the JPEG quality to 80%
  // In this case we need to pass the desired SaveFormat to the ImageSaveOptions constructor 
  // to signal what type of image to save as
  ImageSaveOptions imageOptions = new ImageSaveOptions(SaveFormat.JPEG);
  imageOptions.setPageIndex(2);
  imageOptions.setPageCount(1);
  imageOptions.setJpegQuality(80);
  doc.save(getArtifactsDir() + "Rendering.SaveAsImage.CustomJpgOptions.jpg", imageOptions);

  Example:

  Converts every page of a DOC file into a separate scalable EMF file.

  Document doc = new Document(getMyDir() + "Rendering.docx");
  
  ImageSaveOptions options = new ImageSaveOptions(SaveFormat.EMF);
  options.setPageCount(1);
  
  for (int i = 0; i < doc.getPageCount(); i++) {
      options.setPageIndex(i);
      doc.save(getArtifactsDir() + "Rendering.SaveToEmf." + Integer.toString(i) + ".emf", options);
  }

  Example:

  Converts a whole document to PDF with three levels in the document outline.

  Document doc = new Document(getMyDir() + "Rendering.docx");
  
  PdfSaveOptions options = new PdfSaveOptions();
  options.getOutlineOptions().setHeadingsOutlineLevels(3);
  options.getOutlineOptions().setExpandedOutlineLevels(1);
  
  doc.save(getArtifactsDir() + "Rendering.SaveToPdfWithOutline.pdf", options);

• save

  public SaveOutputParameters save(java.lang.String fileName, int saveFormat)
                           throws java.lang.Exception

  Saves the document to a file in the specified format.

  Parameters:

  fileName - The name for the document. If a document with the specified file name already exists, the existing document is overwritten.

  saveFormat - A SaveFormat value. The format in which to save the document.

  Returns:

  Additional information that you can optionally use.

  Example:

  Shows how to convert from DOCX to HTML format.

  Document doc = new Document(getMyDir() + "Document.docx");
  doc.save(getArtifactsDir() + "Document.ConvertToHtml.html", SaveFormat.HTML);

• selectNodes

  public NodeList selectNodes(java.lang.String xpath)

  Selects a list of nodes matching the XPath expression.

  Only expressions with element names are supported at the moment. Expressions that use attribute names are not supported.

  Parameters:

  xpath - The XPath expression.

  Returns:

  A list of nodes matching the XPath query.

  Example:

  Shows how to select certain nodes by using an XPath expression.

  Document doc = new Document(getMyDir() + "Tables.docx");
  
  // This expression will extract all paragraph nodes which are descendants of any table node in the document
  // This will return any paragraphs which are in a table
  NodeList nodeList = doc.selectNodes("//Table//Paragraph");
  
  // Iterate through the list with an enumerator and print the contents of every paragraph in each cell of the table
  int index = 0;
  
  Iterator<Node> e = nodeList.iterator();
  while (e.hasNext()) {
      Node currentNode = e.next();
      System.out.println(MessageFormat.format("Table paragraph index {0}, contents: \"{1}\"", index++, currentNode.getText().trim()));
  }
  
  // This expression will select any paragraphs that are direct children of any body node in the document
  nodeList = doc.selectNodes("//Body/Paragraph");
  
  // We can treat the list as an array too
  Assert.assertEquals(nodeList.toArray().length, 4);
  
  // Use SelectSingleNode to select the first result of the same expression as above
  Node node = doc.selectSingleNode("//Body/Paragraph");
  
  Assert.assertEquals(Paragraph.class, node.getClass());

  Example:

  Shows how to test if a node is inside a field by using an XPath expression.

  Document doc = new Document(getMyDir() + "Mail merge destination - Northwind employees.docx");
  
  // Evaluate the XPath expression. The resulting NodeList will contain all nodes found inside a field a field (between FieldStart 
  // and FieldEnd exclusive). There can however be FieldStart and FieldEnd nodes in the list if there are nested fields 
  // in the path. Currently does not find rare fields in which the FieldCode or FieldResult spans across multiple paragraphs
  NodeList resultList =
          doc.selectNodes("//FieldStart/following-sibling::node()[following-sibling::FieldEnd]");
  
  // Check if the specified run is one of the nodes that are inside the field
  System.out.println("Contents of the first Run node that's part of a field: {resultList.First(n => n.NodeType == NodeType.Run).GetText().Trim()}");

• selectSingleNode

  public Node selectSingleNode(java.lang.String xpath)

  Selects the first Node that matches the XPath expression.

  Only expressions with element names are supported at the moment. Expressions that use attribute names are not supported.

  Parameters:

  xpath - The XPath expression.

  Returns:

  The first Node that matches the XPath query or null if no matching node is found.

  Example:

  Shows how to select certain nodes by using an XPath expression.

  Document doc = new Document(getMyDir() + "Tables.docx");
  
  // This expression will extract all paragraph nodes which are descendants of any table node in the document
  // This will return any paragraphs which are in a table
  NodeList nodeList = doc.selectNodes("//Table//Paragraph");
  
  // Iterate through the list with an enumerator and print the contents of every paragraph in each cell of the table
  int index = 0;
  
  Iterator<Node> e = nodeList.iterator();
  while (e.hasNext()) {
      Node currentNode = e.next();
      System.out.println(MessageFormat.format("Table paragraph index {0}, contents: \"{1}\"", index++, currentNode.getText().trim()));
  }
  
  // This expression will select any paragraphs that are direct children of any body node in the document
  nodeList = doc.selectNodes("//Body/Paragraph");
  
  // We can treat the list as an array too
  Assert.assertEquals(nodeList.toArray().length, 4);
  
  // Use SelectSingleNode to select the first result of the same expression as above
  Node node = doc.selectSingleNode("//Body/Paragraph");
  
  Assert.assertEquals(Paragraph.class, node.getClass());

• startTrackRevisions

  public void startTrackRevisions(java.lang.String author)

  Starts automatically marking all further changes you make to the document programmatically as revision changes.

  If you call this method and then make some changes to the document programmatically, save the document and later open the document in MS Word you will see these changes as revisions.

  Currently Aspose.Words supports tracking of node insertions and deletions only. Formatting changes are not recorded as revisions.

  Automatic tracking of changes is supported both when modifying this document through node manipulations as well as when using DocumentBuilder

  This method does not change the TrackRevisions option and does not use its value for the purposes of revision tracking.

  Parameters:

  author - Initials of the author to use for revisions.

  See Also:

  stopTrackRevisions()

  Example:

  Shows how to track revisions while editing a document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Editing a document usually does not count as a revision until we begin tracking them.
  builder.write("Hello world! ");
  
  Assert.assertEquals(0, doc.getRevisions().getCount());
  Assert.assertFalse(doc.getFirstSection().getBody().getParagraphs().get(0).getRuns().get(0).isInsertRevision());
  
  doc.startTrackRevisions("John Doe");
  
  builder.write("Hello again! ");
  
  Assert.assertEquals(1, doc.getRevisions().getCount());
  Assert.assertTrue(doc.getFirstSection().getBody().getParagraphs().get(0).getRuns().get(1).isInsertRevision());
  Assert.assertEquals("John Doe", doc.getRevisions().get(0).getAuthor());
  
  // Stop tracking revisions to not count any future edits as revisions.
  doc.stopTrackRevisions();
  builder.write("Hello again! ");
  
  Assert.assertEquals(1, doc.getRevisions().getCount());
  Assert.assertFalse(doc.getFirstSection().getBody().getParagraphs().get(0).getRuns().get(2).isInsertRevision());
  
  // Creating revisions gives them a date and time of the operation.
  // We can disable this by passing DateTime.MinValue when we start tracking revisions.
  doc.startTrackRevisions("John Doe", new Date());
  builder.write("Hello again! ");
  
  Assert.assertEquals(2, doc.getRevisions().getCount());
  Assert.assertEquals("John Doe", doc.getRevisions().get(1).getAuthor());
  Assert.assertEquals(new Date(), doc.getRevisions().get(1).getDateTime());
  
  // We can accept/reject these revisions programmatically
  // by calling methods such as Document.AcceptAllRevisions, or each revision's Accept method.
  // In Microsoft Word, they can be processed via Review -> Changes.
  doc.save(getArtifactsDir() + "Document.StartTrackRevisions.docx");

• startTrackRevisions

  public void startTrackRevisions(java.lang.String author, java.util.Date dateTime)

  Starts automatically marking all further changes you make to the document programmatically as revision changes.

  If you call this method and then make some changes to the document programmatically, save the document and later open the document in MS Word you will see these changes as revisions.

  Currently Aspose.Words supports tracking of node insertions and deletions only. Formatting changes are not recorded as revisions.

  Automatic tracking of changes is supported both when modifying this document through node manipulations as well as when using DocumentBuilder

  This method does not change the TrackRevisions option and does not use its value for the purposes of revision tracking.

  Parameters:

  author - Initials of the author to use for revisions.

  dateTime - The date and time to use for revisions.

  See Also:

  stopTrackRevisions()

  Example:

  Shows how to track revisions while editing a document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Editing a document usually does not count as a revision until we begin tracking them.
  builder.write("Hello world! ");
  
  Assert.assertEquals(0, doc.getRevisions().getCount());
  Assert.assertFalse(doc.getFirstSection().getBody().getParagraphs().get(0).getRuns().get(0).isInsertRevision());
  
  doc.startTrackRevisions("John Doe");
  
  builder.write("Hello again! ");
  
  Assert.assertEquals(1, doc.getRevisions().getCount());
  Assert.assertTrue(doc.getFirstSection().getBody().getParagraphs().get(0).getRuns().get(1).isInsertRevision());
  Assert.assertEquals("John Doe", doc.getRevisions().get(0).getAuthor());
  
  // Stop tracking revisions to not count any future edits as revisions.
  doc.stopTrackRevisions();
  builder.write("Hello again! ");
  
  Assert.assertEquals(1, doc.getRevisions().getCount());
  Assert.assertFalse(doc.getFirstSection().getBody().getParagraphs().get(0).getRuns().get(2).isInsertRevision());
  
  // Creating revisions gives them a date and time of the operation.
  // We can disable this by passing DateTime.MinValue when we start tracking revisions.
  doc.startTrackRevisions("John Doe", new Date());
  builder.write("Hello again! ");
  
  Assert.assertEquals(2, doc.getRevisions().getCount());
  Assert.assertEquals("John Doe", doc.getRevisions().get(1).getAuthor());
  Assert.assertEquals(new Date(), doc.getRevisions().get(1).getDateTime());
  
  // We can accept/reject these revisions programmatically
  // by calling methods such as Document.AcceptAllRevisions, or each revision's Accept method.
  // In Microsoft Word, they can be processed via Review -> Changes.
  doc.save(getArtifactsDir() + "Document.StartTrackRevisions.docx");

• stopTrackRevisions

  public void stopTrackRevisions()

  Stops automatic marking of document changes as revisions.

  See Also:

  startTrackRevisions(java.lang.String,java.util.Date)

  Example:

  Shows how to track revisions while editing a document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Editing a document usually does not count as a revision until we begin tracking them.
  builder.write("Hello world! ");
  
  Assert.assertEquals(0, doc.getRevisions().getCount());
  Assert.assertFalse(doc.getFirstSection().getBody().getParagraphs().get(0).getRuns().get(0).isInsertRevision());
  
  doc.startTrackRevisions("John Doe");
  
  builder.write("Hello again! ");
  
  Assert.assertEquals(1, doc.getRevisions().getCount());
  Assert.assertTrue(doc.getFirstSection().getBody().getParagraphs().get(0).getRuns().get(1).isInsertRevision());
  Assert.assertEquals("John Doe", doc.getRevisions().get(0).getAuthor());
  
  // Stop tracking revisions to not count any future edits as revisions.
  doc.stopTrackRevisions();
  builder.write("Hello again! ");
  
  Assert.assertEquals(1, doc.getRevisions().getCount());
  Assert.assertFalse(doc.getFirstSection().getBody().getParagraphs().get(0).getRuns().get(2).isInsertRevision());
  
  // Creating revisions gives them a date and time of the operation.
  // We can disable this by passing DateTime.MinValue when we start tracking revisions.
  doc.startTrackRevisions("John Doe", new Date());
  builder.write("Hello again! ");
  
  Assert.assertEquals(2, doc.getRevisions().getCount());
  Assert.assertEquals("John Doe", doc.getRevisions().get(1).getAuthor());
  Assert.assertEquals(new Date(), doc.getRevisions().get(1).getDateTime());
  
  // We can accept/reject these revisions programmatically
  // by calling methods such as Document.AcceptAllRevisions, or each revision's Accept method.
  // In Microsoft Word, they can be processed via Review -> Changes.
  doc.save(getArtifactsDir() + "Document.StartTrackRevisions.docx");

• toString

  public java.lang.String toString(SaveOptions saveOptions)
                 throws java.lang.Exception

  Exports the content of the node into a string using the specified save options.

  Parameters:

  saveOptions - Specifies the options that control how the node is saved.

  Returns:

  The content of the node in the specified format.

  Example:

  Exports the content of a node to String in HTML format.

  Document doc = new Document(getMyDir() + "Document.docx");
  
  // Extract the last paragraph in the document to convert to HTML
  Node node = doc.getLastSection().getBody().getLastParagraph();
  
  // When ToString is called using the html SaveFormat overload then the node is converted directly to html
  Assert.assertEquals("<p style=\"margin-top:0pt; margin-bottom:8pt; line-height:108%; font-size:12pt\">" +
          "<span style=\"font-family:'Times New Roman'\">Hello World!</span>" +
          "</p>", node.toString(SaveFormat.HTML));
  
  // We can also modify the result of this conversion using a SaveOptions object
  HtmlSaveOptions saveOptions = new HtmlSaveOptions();
  saveOptions.setExportRelativeFontSize(true);
  
  Assert.assertEquals("<p style=\"margin-top:0pt; margin-bottom:8pt; line-height:108%\">" +
          "<span style=\"font-family:'Times New Roman'\">Hello World!</span>" +
          "</p>", node.toString(saveOptions));

• toString

  public java.lang.String toString(int saveFormat)
                 throws java.lang.Exception

  Exports the content of the node into a string in the specified format.

  Returns:

  The content of the node in the specified format.

  Parameters:

  saveFormat - A SaveFormat value.

  Example:

  Shows how to extract the label of each paragraph in a list as a value or a String.

  Document doc = new Document(getMyDir() + "Rendering.docx");
  doc.updateListLabels();
  int listParaCount = 1;
  
  for (Paragraph paragraph : (Iterable<Paragraph>) doc.getChildNodes(NodeType.PARAGRAPH, true)) {
      // Find if we have the paragraph list. In our document our list uses plain arabic numbers,
      // which start at three and ends at six
      if (paragraph.getListFormat().isListItem()) {
          System.out.println(MessageFormat.format("List item paragraph #{0}", listParaCount));
  
          // This is the text we get when actually getting when we output this node to text format
          // The list labels are not included in this text output. Trim any paragraph formatting characters
          String paragraphText = paragraph.toString(SaveFormat.TEXT).trim();
          System.out.println("Exported Text: " + paragraphText);
  
          ListLabel label = paragraph.getListLabel();
          // This gets the position of the paragraph in current level of the list. If we have a list with multiple level then this
          // will tell us what position it is on that particular level
          System.out.println("\tNumerical Id: " + label.getLabelValue());
  
          // Combine them together to include the list label with the text in the output
          System.out.println("\tList label combined with text: " + label.getLabelString() + " " + paragraphText);
  
          listParaCount++;
      }
  }

  Example:

  Exports the content of a node to String in HTML format.

  Document doc = new Document(getMyDir() + "Document.docx");
  
  // Extract the last paragraph in the document to convert to HTML
  Node node = doc.getLastSection().getBody().getLastParagraph();
  
  // When ToString is called using the html SaveFormat overload then the node is converted directly to html
  Assert.assertEquals("<p style=\"margin-top:0pt; margin-bottom:8pt; line-height:108%; font-size:12pt\">" +
          "<span style=\"font-family:'Times New Roman'\">Hello World!</span>" +
          "</p>", node.toString(SaveFormat.HTML));
  
  // We can also modify the result of this conversion using a SaveOptions object
  HtmlSaveOptions saveOptions = new HtmlSaveOptions();
  saveOptions.setExportRelativeFontSize(true);
  
  Assert.assertEquals("<p style=\"margin-top:0pt; margin-bottom:8pt; line-height:108%\">" +
          "<span style=\"font-family:'Times New Roman'\">Hello World!</span>" +
          "</p>", node.toString(saveOptions));

  Example:

  Shows the difference between calling the GetText and ToString methods on a node.

  Document doc = new Document();
  
  DocumentBuilder builder = new DocumentBuilder(doc);
  builder.insertField("MERGEFIELD Field");
  
  // GetText will retrieve the visible text as well as field codes and special characters.
  Assert.assertEquals("\u0013MERGEFIELD Field\u0014«Field»\u0015\f", doc.getText());
  
  // ToString will give us the document's appearance if saved to a passed save format.
  Assert.assertEquals("«Field»\r\n", doc.toString(SaveFormat.TEXT));

• unlinkFields

  public void unlinkFields()
                   throws java.lang.Exception

  Unlinks fields in the whole document.

  Replaces all the fields in the whole document with their most recent results.

  To unlink fields in a specific part of the document use Range.unlinkFields().

  Example:

  Shows how to unlink all fields in the document.

  Document doc = new Document(getMyDir() + "Linked fields.docx");
  
  doc.unlinkFields();

• unprotect

  public void unprotect()

  Removes protection from the document regardless of the password.

  This method unprotects the document even if it has a protection password.

  Note that document protection is different from write protection. Write protection is specified using the WriteProtection.

  Example:

  Shows how to protect and unprotect a document.

  Document doc = new Document();
  doc.protect(ProtectionType.READ_ONLY, "password");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, doc.getProtectionType());
  
  // If we open this document with Microsoft Word intending to edit it,
  // we will need to apply the password to get through the protection.
  doc.save(getArtifactsDir() + "Document.Protect.docx");
  
  // Note that the protection only applies to Microsoft Word users opening our document.
  // We have not encrypted the document in any way, and we do not need the password to open and edit it programmatically.
  Document protectedDoc = new Document(getArtifactsDir() + "Document.Protect.docx");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, protectedDoc.getProtectionType());
  
  DocumentBuilder builder = new DocumentBuilder(protectedDoc);
  builder.writeln("Text added to a protected document.");
  
  // There are two ways of removing protection from a document.
  // 1 - With no password:
  doc.unprotect();
  
  Assert.assertEquals(ProtectionType.NO_PROTECTION, doc.getProtectionType());
  
  doc.protect(ProtectionType.READ_ONLY, "NewPassword");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, doc.getProtectionType());
  
  doc.unprotect("WrongPassword");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, doc.getProtectionType());
  
  // 2 - With the correct password:
  doc.unprotect("NewPassword");
  
  Assert.assertEquals(ProtectionType.NO_PROTECTION, doc.getProtectionType());

• unprotect

  public boolean unprotect(java.lang.String password)

  Removes protection from the document if a correct password is specified.

  This method unprotects the document only if a correct password is specified.

  Note that document protection is different from write protection. Write protection is specified using the WriteProtection.

  Parameters:

  password - The password to unprotect the document with.

  Returns:

  True if a correct password was specified and the document was unprotected.

  Example:

  Shows how to protect and unprotect a document.

  Document doc = new Document();
  doc.protect(ProtectionType.READ_ONLY, "password");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, doc.getProtectionType());
  
  // If we open this document with Microsoft Word intending to edit it,
  // we will need to apply the password to get through the protection.
  doc.save(getArtifactsDir() + "Document.Protect.docx");
  
  // Note that the protection only applies to Microsoft Word users opening our document.
  // We have not encrypted the document in any way, and we do not need the password to open and edit it programmatically.
  Document protectedDoc = new Document(getArtifactsDir() + "Document.Protect.docx");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, protectedDoc.getProtectionType());
  
  DocumentBuilder builder = new DocumentBuilder(protectedDoc);
  builder.writeln("Text added to a protected document.");
  
  // There are two ways of removing protection from a document.
  // 1 - With no password:
  doc.unprotect();
  
  Assert.assertEquals(ProtectionType.NO_PROTECTION, doc.getProtectionType());
  
  doc.protect(ProtectionType.READ_ONLY, "NewPassword");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, doc.getProtectionType());
  
  doc.unprotect("WrongPassword");
  
  Assert.assertEquals(ProtectionType.READ_ONLY, doc.getProtectionType());
  
  // 2 - With the correct password:
  doc.unprotect("NewPassword");
  
  Assert.assertEquals(ProtectionType.NO_PROTECTION, doc.getProtectionType());

• updateFields

  public void updateFields()
                   throws java.lang.Exception

  Updates the values of fields in the whole document.

  When you open, modify and then save a document, Aspose.Words does not update fields automatically, it keeps them intact. Therefore, you would usually want to call this method before saving if you have modified the document programmatically and want to make sure the proper (calculated) field values appear in the saved document.

  There is no need to update fields after executing a mail merge because mail merge is a kind of field update and automatically updates all fields in the document.

  This method does not update all field types. For the detailed list of supported field types, see the Programmers Guide.

  This method does not update fields that are related to the page layout algorithms (e.g. PAGE, PAGES, PAGEREF). The page layout-related fields are updated when you render a document or call updatePageLayout().

  Use the normalizeFieldTypes() method before fields updating if there were document changes that affected field types.

  To update fields in a specific part of the document use Range.updateFields().

  Example:

  Shows how to insert a Table of contents (TOC) into a document using heading styles as entries.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Insert a table of contents for the first page of the document.
  // Configure the table to pick up paragraphs with headings of levels 1 to 3.
  // Also, set its entries to be hyperlinks that will take us
  // to the location of the heading when left-clicked in Microsoft Word.
  builder.insertTableOfContents("\\o \"1-3\" \\h \\z \\u");
  builder.insertBreak(BreakType.PAGE_BREAK);
  
  // Populate the table of contents by adding paragraphs with heading styles.
  // Each such heading will create an entry in the table, as long as its heading level is between 1 and 3.
  builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
  builder.writeln("Heading 1");
  
  builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
  builder.writeln("Heading 1.1");
  builder.writeln("Heading 1.2");
  
  builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_1);
  builder.writeln("Heading 2");
  builder.writeln("Heading 3");
  
  builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
  builder.writeln("Heading 3.1");
  
  builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_3);
  builder.writeln("Heading 3.1.1");
  builder.writeln("Heading 3.1.2");
  builder.writeln("Heading 3.1.3");
  
  builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_4);
  builder.writeln("Heading 3.1.3.1");
  builder.writeln("Heading 3.1.3.2");
  
  builder.getParagraphFormat().setStyleIdentifier(StyleIdentifier.HEADING_2);
  builder.writeln("Heading 3.2");
  builder.writeln("Heading 3.3");
  
  // A table of contents is a field of a type that needs to be updated to show an up-to-date result.
  doc.updateFields();
  doc.save(getArtifactsDir() + "DocumentBuilder.InsertToc.docx");

  Example:

  Shows how to set user details and display them with fields.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Set user information
  UserInformation userInformation = new UserInformation();
  userInformation.setName("John Doe");
  userInformation.setInitials("J. D.");
  userInformation.setAddress("123 Main Street");
  doc.getFieldOptions().setCurrentUser(userInformation);
  
  // Insert fields that reference our user information
  Assert.assertEquals(userInformation.getName(), builder.insertField(" USERNAME ").getResult());
  Assert.assertEquals(userInformation.getInitials(), builder.insertField(" USERINITIALS ").getResult());
  Assert.assertEquals(userInformation.getAddress(), builder.insertField(" USERADDRESS ").getResult());
  
  // The field options object also has a static default user value that fields from many documents can refer to
  UserInformation.getDefaultUser().setName("Default User");
  UserInformation.getDefaultUser().setInitials("D. U.");
  UserInformation.getDefaultUser().setAddress("One Microsoft Way");
  doc.getFieldOptions().setCurrentUser(UserInformation.getDefaultUser());
  
  Assert.assertEquals("Default User", builder.insertField(" USERNAME ").getResult());
  Assert.assertEquals("D. U.", builder.insertField(" USERINITIALS ").getResult());
  Assert.assertEquals("One Microsoft Way", builder.insertField(" USERADDRESS ").getResult());
  
  doc.updateFields();
  doc.save(getArtifactsDir() + "FieldOptions.FieldOptionsCurrentUser.docx");

  Example:

  Shows to use the QUOTE field.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  // Insert a QUOTE field, which will display content from the Text attribute
  FieldQuote field = (FieldQuote) builder.insertField(FieldType.FIELD_QUOTE, true);
  field.setText("\"Quoted text\"");
  
  Assert.assertEquals(" QUOTE  \"\\\"Quoted text\\\"\"", field.getFieldCode());
  
  // Insert a QUOTE field with a nested DATE field
  // DATE fields normally update their value to the current date every time the document is opened
  // Nesting the DATE field inside the QUOTE field like this will freeze its value to the date when we created the document
  builder.write("\nDocument creation date: ");
  field = (FieldQuote) builder.insertField(FieldType.FIELD_QUOTE, true);
  builder.moveTo(field.getSeparator());
  builder.insertField(FieldType.FIELD_DATE, true);
  
  Assert.assertEquals(" QUOTE \u0013 DATE \u0014" + LocalDate.now().format(DateTimeFormatter.ofPattern("M/d/YYYY")) + "\u0015", field.getFieldCode());
  
  // Some field types don't display the correct result until they are manually updated
  Assert.assertEquals("", doc.getRange().getFields().get(0).getResult());
  
  doc.updateFields();
  
  Assert.assertEquals("\"Quoted text\"", doc.getRange().getFields().get(0).getResult());
  
  doc.save(getArtifactsDir() + "Field.QUOTE.docx");

• updateListLabels

  public void updateListLabels()
                       throws java.lang.Exception

  Updates list labels for all list items in the document.

  This method updates list label properties such as ListLabel.LabelValue and ListLabel.LabelString for each Paragraph.ListLabel object in the document.

  Also, this method is sometimes implicitly called when updating fields in the document. This is required because some fields that may reference list numbers (such as TOC or REF) need them be up-to-date.

  Example:

  Shows how to extract the label of each paragraph in a list as a value or a String.

  Document doc = new Document(getMyDir() + "Rendering.docx");
  doc.updateListLabels();
  int listParaCount = 1;
  
  for (Paragraph paragraph : (Iterable<Paragraph>) doc.getChildNodes(NodeType.PARAGRAPH, true)) {
      // Find if we have the paragraph list. In our document our list uses plain arabic numbers,
      // which start at three and ends at six
      if (paragraph.getListFormat().isListItem()) {
          System.out.println(MessageFormat.format("List item paragraph #{0}", listParaCount));
  
          // This is the text we get when actually getting when we output this node to text format
          // The list labels are not included in this text output. Trim any paragraph formatting characters
          String paragraphText = paragraph.toString(SaveFormat.TEXT).trim();
          System.out.println("Exported Text: " + paragraphText);
  
          ListLabel label = paragraph.getListLabel();
          // This gets the position of the paragraph in current level of the list. If we have a list with multiple level then this
          // will tell us what position it is on that particular level
          System.out.println("\tNumerical Id: " + label.getLabelValue());
  
          // Combine them together to include the list label with the text in the output
          System.out.println("\tList label combined with text: " + label.getLabelString() + " " + paragraphText);
  
          listParaCount++;
      }
  }

• updatePageLayout

  public void updatePageLayout()
                       throws java.lang.Exception

  Rebuilds the page layout of the document.

  This method formats a document into pages and updates the page number related fields in the document such as PAGE, PAGES, PAGEREF and REF. The up-to-date page layout information is required for a correct rendering of the document to fixed-page formats.

  This method is automatically invoked when you first convert a document to PDF, XPS, image or print it. However, if you modify the document after rendering and then attempt to render it again - Aspose.Words will not update the page layout automatically. In this case you should call updatePageLayout() before rendering again.

  Example:

  Shows when to request page layout of the document to be recalculated.

  Document doc = new Document(getMyDir() + "Rendering.docx");
  
  // Saving a document to PDF or to image or printing for the first time will automatically
  // layout document pages and this information will be cached inside the document
  doc.save(getArtifactsDir() + "Rendering.UpdatePageLayout.1.pdf");
  
  // Modify the document in any way
  doc.getStyles().get("Normal").getFont().setSize(6.0);
  doc.getSections().get(0).getPageSetup().setOrientation(com.aspose.words.Orientation.LANDSCAPE);
  
  // In the current version of Aspose.Words, modifying the document does not automatically rebuild 
  // the cached page layout. If you want to save to PDF or render a modified document again,
  // you need to manually request page layout to be updated
  doc.updatePageLayout();
  
  doc.save(getArtifactsDir() + "Rendering.UpdatePageLayout.2.pdf");

• updateTableLayout

  public void updateTableLayout()

  Updates widths of cells and tables in the document according to their preferred widths and content. You do not need to call this method if the tables appear correct in the output document.

  You do not normally need to call this method as cell and table widths are maintained automatically. You can call this method before exporting to PDF (or any other fixed-page format), only in rare cases where you confirmed that tables appear incorrectly laid out in the output document. Calling this method might help to correct the output.

  Example:

  Shows how to preserve a table's layout when saving to .txt.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  Table table = builder.startTable();
  builder.insertCell();
  builder.write("Cell 1");
  builder.insertCell();
  builder.write("Cell 2");
  builder.insertCell();
  builder.write("Cell 3");
  builder.endTable();
  
  // Create a SaveOptions object to prepare this document to be saved to .txt.
  TxtSaveOptions options = new TxtSaveOptions();
  options.setPreserveTableLayout(true);
  
  // Previewing the appearance of the document in .txt form shows that the table will not be represented accurately.
  Assert.assertEquals(0.0d, table.getFirstRow().getCells().get(0).getCellFormat().getWidth());
  Assert.assertEquals("CCC\r\neee\r\nlll\r\nlll\r\n   \r\n123\r\n\r\n", doc.toString(options));
  
  // We can call UpdateTableLayout() to fix some of these issues.
  doc.updateTableLayout();
  
  Assert.assertEquals("Cell 1             Cell 2             Cell 3\r\n\r\n", doc.toString(options));
  Assert.assertEquals(155.0d, table.getFirstRow().getCells().get(0).getCellFormat().getWidth(), 2f);

• updateThumbnail

  public void updateThumbnail()
                      throws java.lang.Exception

  Updates BuiltInDocumentProperties.Thumbnail of the document using default options.

  Example:

  Shows how to update a document's thumbnail.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.writeln("Hello world!");
  builder.insertImage(getImageDir() + "Logo.jpg");
  
  // There are two ways of setting a thumbnail image when saving a document to .epub.
  // 1 -  Use the document's first page:
  doc.updateThumbnail();
  doc.save(getArtifactsDir() + "Document.UpdateThumbnail.FirstPage.epub");
  
  // 2 -  Use the first image found in the document:
  ThumbnailGeneratingOptions options = new ThumbnailGeneratingOptions();
  options.setThumbnailSize(new Dimension(400, 400));
  options.setGenerateFromFirstPage(false);
  
  doc.updateThumbnail(options);
  doc.save(getArtifactsDir() + "Document.UpdateThumbnail.FirstImage.epub");

• updateThumbnail

  public void updateThumbnail(ThumbnailGeneratingOptions options)
                      throws java.lang.Exception

  Updates BuiltInDocumentProperties.Thumbnail of the document according to the specified options.

  The ThumbnailGeneratingOptions allows you to specify the source of thumbnail, size and other options. If attempt to generate thumbnail fails, doesn't change one.

  Parameters:

  options - The generating options to use.

  Example:

  Shows how to update a document's thumbnail.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.writeln("Hello world!");
  builder.insertImage(getImageDir() + "Logo.jpg");
  
  // There are two ways of setting a thumbnail image when saving a document to .epub.
  // 1 -  Use the document's first page:
  doc.updateThumbnail();
  doc.save(getArtifactsDir() + "Document.UpdateThumbnail.FirstPage.epub");
  
  // 2 -  Use the first image found in the document:
  ThumbnailGeneratingOptions options = new ThumbnailGeneratingOptions();
  options.setThumbnailSize(new Dimension(400, 400));
  options.setGenerateFromFirstPage(false);
  
  doc.updateThumbnail(options);
  doc.save(getArtifactsDir() + "Document.UpdateThumbnail.FirstImage.epub");

• updateWordCount

  public void updateWordCount()
                      throws java.lang.Exception

  Updates word count properties of the document.

  UpdateWordCount recalculates and updates Characters, Words and Paragraphs properties in the BuiltInDocumentProperties collection of the Document.

  Note that UpdateWordCount does not update number of lines and pages properties. Use the updateWordCount() overload and pass True value as a parameter to do that.

  When you use an evaluation version, the evaluation watermark will also be included in the word count.

  Example:

  Shows how to update all list labels in a document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.writeln("Lorem ipsum dolor sit amet, consectetur adipiscing elit, " +
          "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.");
  builder.write("Ut enim ad minim veniam, " +
          "quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.");
  
  // Aspose.Words does not track document metrics like these in real time.
  Assert.assertEquals(0, doc.getBuiltInDocumentProperties().getCharacters());
  Assert.assertEquals(0, doc.getBuiltInDocumentProperties().getWords());
  Assert.assertEquals(1, doc.getBuiltInDocumentProperties().getParagraphs());
  Assert.assertEquals(1, doc.getBuiltInDocumentProperties().getLines());
  
  // To get accurate values for three of these properties, we will need to update them manually.
  doc.updateWordCount();
  
  Assert.assertEquals(196, doc.getBuiltInDocumentProperties().getCharacters());
  Assert.assertEquals(36, doc.getBuiltInDocumentProperties().getWords());
  Assert.assertEquals(2, doc.getBuiltInDocumentProperties().getParagraphs());
  
  // For the line count, we will need to call a specific overload of the updating method.
  Assert.assertEquals(1, doc.getBuiltInDocumentProperties().getLines());
  
  doc.updateWordCount(true);
  
  Assert.assertEquals(4, doc.getBuiltInDocumentProperties().getLines());

• updateWordCount

  public void updateWordCount(boolean updateLinesCount)
                      throws java.lang.Exception

  Updates word count properties of the document, optionally updates BuiltInDocumentProperties.Lines property.

  This method will rebuild page layout of the document.

  Parameters:

  updateLinesCount - True if number of lines in the document shall be calculated.

  Example:

  Shows how to update all list labels in a document.

  Document doc = new Document();
  DocumentBuilder builder = new DocumentBuilder(doc);
  
  builder.writeln("Lorem ipsum dolor sit amet, consectetur adipiscing elit, " +
          "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.");
  builder.write("Ut enim ad minim veniam, " +
          "quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.");
  
  // Aspose.Words does not track document metrics like these in real time.
  Assert.assertEquals(0, doc.getBuiltInDocumentProperties().getCharacters());
  Assert.assertEquals(0, doc.getBuiltInDocumentProperties().getWords());
  Assert.assertEquals(1, doc.getBuiltInDocumentProperties().getParagraphs());
  Assert.assertEquals(1, doc.getBuiltInDocumentProperties().getLines());
  
  // To get accurate values for three of these properties, we will need to update them manually.
  doc.updateWordCount();
  
  Assert.assertEquals(196, doc.getBuiltInDocumentProperties().getCharacters());
  Assert.assertEquals(36, doc.getBuiltInDocumentProperties().getWords());
  Assert.assertEquals(2, doc.getBuiltInDocumentProperties().getParagraphs());
  
  // For the line count, we will need to call a specific overload of the updating method.
  Assert.assertEquals(1, doc.getBuiltInDocumentProperties().getLines());
  
  doc.updateWordCount(true);
  
  Assert.assertEquals(4, doc.getBuiltInDocumentProperties().getLines());