com.aspose.words

Class DocumentProperty

  • java.lang.Object
    • com.aspose.words.DocumentProperty
  • All Implemented Interfaces:
    java.lang.Cloneable
    public class DocumentProperty 
    extends java.lang.Object

Represents a custom or built-in document property.

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()));
}
See Also:
DocumentPropertyCollection

Property Getters/Setters Summary
booleanisLinkToContent()
Shows whether this property is linked to content or not.
java.lang.StringgetLinkSource()
Gets the source of a linked custom document property.
java.lang.StringgetName()
Returns the name of the property.
intgetType()
Gets the data type of the property. The value of the property is PropertyType integer constant.
java.lang.ObjectgetValue()
void
setValue(java.lang.Objectvalue)
           Gets or sets the value of the property.
 
Method Summary
booleantoBool()
Returns the property value as bool.
byte[]toByteArray()
Returns the property value as byte array.
java.util.DatetoDateTime()
Returns the property value as DateTime in UTC.
doubletoDouble()
Returns the property value as double.
inttoInt()
Returns the property value as integer.
java.lang.StringtoString()
Returns the property value as a string formatted according to the current locale.
 

    • Property Getters/Setters Detail

      • isLinkToContent

        public boolean isLinkToContent()
        
        Shows whether this property is linked to content or not.

        Example:

        Shows how to link a custom document property to a bookmark.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        builder.startBookmark("MyBookmark");
        builder.write("MyBookmark contents.");
        builder.endBookmark("MyBookmark");
        
        // Add linked to content property
        CustomDocumentProperties customProperties = doc.getCustomDocumentProperties();
        DocumentProperty customProperty = customProperties.addLinkToContent("Bookmark", "MyBookmark");
        
        // Check whether the property is linked to content
        Assert.assertEquals(true, customProperty.isLinkToContent());
        Assert.assertEquals("MyBookmark", customProperty.getLinkSource());
        Assert.assertEquals("MyBookmark contents.", customProperty.getValue());
        
        doc.save(getArtifactsDir() + "Properties.LinkCustomDocumentPropertiesToBookmark.docx");
      • getLinkSource

        public java.lang.String getLinkSource()
        
        Gets the source of a linked custom document property.

        Example:

        Shows how to link a custom document property to a bookmark.
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        builder.startBookmark("MyBookmark");
        builder.write("MyBookmark contents.");
        builder.endBookmark("MyBookmark");
        
        // Add linked to content property
        CustomDocumentProperties customProperties = doc.getCustomDocumentProperties();
        DocumentProperty customProperty = customProperties.addLinkToContent("Bookmark", "MyBookmark");
        
        // Check whether the property is linked to content
        Assert.assertEquals(true, customProperty.isLinkToContent());
        Assert.assertEquals("MyBookmark", customProperty.getLinkSource());
        Assert.assertEquals("MyBookmark contents.", customProperty.getValue());
        
        doc.save(getArtifactsDir() + "Properties.LinkCustomDocumentPropertiesToBookmark.docx");
      • getName

        public java.lang.String getName()
        
        Returns the name of the property.

        Cannot be null and cannot be an empty string.

        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()));
        }
      • getType

        public int getType()
        
        Gets the data type of the property. The value of the property is PropertyType integer constant.

        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()));
        }

        Example:

        Shows how to add custom properties to a document.
        Document doc = new Document();
        CustomDocumentProperties properties = doc.getCustomDocumentProperties();
        
        // The custom property collection will be empty by default
        Assert.assertEquals(0, properties.getCount());
        
        // We can populate it with key/value pairs with a variety of value types
        properties.add("Authorized", true);
        properties.add("Authorized By", "John Doe");
        properties.add("Authorized Date", new Date());
        properties.add("Authorized Revision", doc.getBuiltInDocumentProperties().getRevisionNumber());
        properties.add("Authorized Amount", 123.45);
        
        // Custom properties are automatically sorted in alphabetic order
        Assert.assertEquals(properties.indexOf("Authorized Amount"), 1);
        Assert.assertEquals(properties.getCount(), 5);
        
        // Enumerate and print all custom properties
        Iterator<DocumentProperty> enumerator = properties.iterator();
        try {
            while (enumerator.hasNext()) {
                DocumentProperty property = enumerator.next();
                System.out.println(MessageFormat.format("Name: \"{0}\", Type: \"{1}\", Value: \"{2}\"", property.getName(), property.getType(), property.getValue()));
            }
        } finally {
            if (enumerator != null) enumerator.remove();
        }
        
        // We can view/edit custom properties by opening the document and looking in File > Properties > Advanced Properties > Custom
        doc.save(getArtifactsDir() + "Properties.DocumentPropertyCollection.docx");
        
        // We can remove elements from the property collection by index or by name
        properties.removeAt(1);
        Assert.assertFalse(properties.contains("Authorized Amount"));
        Assert.assertEquals(properties.getCount(), 4);
        
        properties.remove("Authorized Revision");
        Assert.assertFalse(properties.contains("Authorized Revision"));
        Assert.assertEquals(properties.getCount(), 3);
        
        // We can also empty the entire custom property collection at once
        properties.clear();
        Assert.assertEquals(properties.getCount(), 0);
      • getValue/setValue

        public java.lang.Object getValue() / public void setValue(java.lang.Object value)
        
        Gets or sets the value of the property.

        Cannot be null.

        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()));
        }
    • Method Detail

      • toBool

        public boolean toBool()
        Returns the property value as bool.

        Throws an exception if the property type is not PropertyType.BOOLEAN.

        Example:

        Shows various type conversion methods of custom document properties.
        Document doc = new Document();
        CustomDocumentProperties properties = doc.getCustomDocumentProperties();
        
        Date authDate = new Date();
        properties.add("Authorized", true);
        properties.add("Authorized By", "John Doe");
        properties.add("Authorized Date", authDate);
        properties.add("Authorized Revision", doc.getBuiltInDocumentProperties().getRevisionNumber());
        properties.add("Authorized Amount", 123.45);
        
        Assert.assertEquals(true, properties.get("Authorized").toBool());
        Assert.assertEquals("John Doe", properties.get("Authorized By").toString());
        Assert.assertEquals(authDate, properties.get("Authorized Date").toDateTime());
        Assert.assertEquals(1, properties.get("Authorized Revision").toInt());
        Assert.assertEquals(123.45d, properties.get("Authorized Amount").toDouble());
      • toByteArray

        public byte[] toByteArray()
        Returns the property value as byte array.

        Throws an exception if the property type is not PropertyType.BYTE_ARRAY.

        Example:

        Shows how to append a thumbnail to an Epub document.
        // Create a blank document and add some text with a DocumentBuilder
        Document doc = new Document();
        DocumentBuilder builder = new DocumentBuilder(doc);
        builder.writeln("Hello world!");
        
        // The thumbnail property resides in a document's built in properties, but is used exclusively by Epub e-book documents
        BuiltInDocumentProperties properties = doc.getBuiltInDocumentProperties();
        
        // Load an image from our file system into a byte array
        byte[] thumbnailBytes = Files.readAllBytes(Paths.get(getImageDir() + "Logo.jpg"));
        
        // Set the value of the Thumbnail property to the array from above
        properties.setThumbnail(thumbnailBytes);
        
        // Our thumbnail should be visible at the start of the document, before the text we added
        doc.save(getArtifactsDir() + "Properties.Thumbnail.epub");
        
        // We can also extract a thumbnail property into a byte array and then into the local file system like this
        DocumentProperty thumbnail = doc.getBuiltInDocumentProperties().get("Thumbnail");
        Files.write(Paths.get(getArtifactsDir() + "Properties.Thumbnail.gif"), thumbnail.toByteArray());
      • toDateTime

        public java.util.Date toDateTime()
        Returns the property value as DateTime in UTC.

        Throws an exception if the property type is not PropertyType.DATE_TIME.

        Microsoft Word stores only the date part (no time) for custom date properties.

        Example:

        Shows various type conversion methods of custom document properties.
        Document doc = new Document();
        CustomDocumentProperties properties = doc.getCustomDocumentProperties();
        
        Date authDate = new Date();
        properties.add("Authorized", true);
        properties.add("Authorized By", "John Doe");
        properties.add("Authorized Date", authDate);
        properties.add("Authorized Revision", doc.getBuiltInDocumentProperties().getRevisionNumber());
        properties.add("Authorized Amount", 123.45);
        
        Assert.assertEquals(true, properties.get("Authorized").toBool());
        Assert.assertEquals("John Doe", properties.get("Authorized By").toString());
        Assert.assertEquals(authDate, properties.get("Authorized Date").toDateTime());
        Assert.assertEquals(1, properties.get("Authorized Revision").toInt());
        Assert.assertEquals(123.45d, properties.get("Authorized Amount").toDouble());

        Example:

        Shows how to create a custom document property with the value of a date and time.
        Document doc = new Document();
        
        doc.getCustomDocumentProperties().add("AuthorizedDate", new Date());
        
        System.out.println("Document authorized on {doc.CustomDocumentProperties[");
      • toDouble

        public double toDouble()
        Returns the property value as double. Throws an exception if the property type is not PropertyType.NUMBER.

        Example:

        Shows various type conversion methods of custom document properties.
        Document doc = new Document();
        CustomDocumentProperties properties = doc.getCustomDocumentProperties();
        
        Date authDate = new Date();
        properties.add("Authorized", true);
        properties.add("Authorized By", "John Doe");
        properties.add("Authorized Date", authDate);
        properties.add("Authorized Revision", doc.getBuiltInDocumentProperties().getRevisionNumber());
        properties.add("Authorized Amount", 123.45);
        
        Assert.assertEquals(true, properties.get("Authorized").toBool());
        Assert.assertEquals("John Doe", properties.get("Authorized By").toString());
        Assert.assertEquals(authDate, properties.get("Authorized Date").toDateTime());
        Assert.assertEquals(1, properties.get("Authorized Revision").toInt());
        Assert.assertEquals(123.45d, properties.get("Authorized Amount").toDouble());
      • toInt

        public int toInt()
        Returns the property value as integer. Throws an exception if the property type is not PropertyType.NUMBER.

        Example:

        Shows various type conversion methods of custom document properties.
        Document doc = new Document();
        CustomDocumentProperties properties = doc.getCustomDocumentProperties();
        
        Date authDate = new Date();
        properties.add("Authorized", true);
        properties.add("Authorized By", "John Doe");
        properties.add("Authorized Date", authDate);
        properties.add("Authorized Revision", doc.getBuiltInDocumentProperties().getRevisionNumber());
        properties.add("Authorized Amount", 123.45);
        
        Assert.assertEquals(true, properties.get("Authorized").toBool());
        Assert.assertEquals("John Doe", properties.get("Authorized By").toString());
        Assert.assertEquals(authDate, properties.get("Authorized Date").toDateTime());
        Assert.assertEquals(1, properties.get("Authorized Revision").toInt());
        Assert.assertEquals(123.45d, properties.get("Authorized Amount").toDouble());
      • toString

        public java.lang.String toString()
        Returns the property value as a string formatted according to the current locale.

        Converts a boolean property into "Y" or "N". Converts a date property into a short date string. For all other types converts a property using Object.ToString().

        Example:

        Shows how to work with custom document properties.
        Document doc = new Document(getMyDir() + "Properties.docx");
        
        // A document's built in properties contains a set of predetermined keys
        // with values such as the author's name or document's word count
        // We can add our own keys and values to a custom properties collection also
        // Before we add a custom property, we need to make sure that one with the same name doesn't already exist
        Assert.assertEquals("Value of custom document property", doc.getCustomDocumentProperties().get("CustomProperty").toString());
        
        doc.getCustomDocumentProperties().add("CustomProperty2", "Value of custom document property #2");
        
        // Iterate over all the custom document properties
        System.out.println("Custom Properties:");
        for (DocumentProperty customDocumentProperty : (Iterable<DocumentProperty>) doc.getCustomDocumentProperties())
        {
            System.out.println(customDocumentProperty.getName());
            System.out.println("\tType:\t{customDocumentProperty.Type}");
            System.out.println("\tValue:\t\"{customDocumentProperty.Value}\"");
        }

        Example:

        Shows various type conversion methods of custom document properties.
        Document doc = new Document();
        CustomDocumentProperties properties = doc.getCustomDocumentProperties();
        
        Date authDate = new Date();
        properties.add("Authorized", true);
        properties.add("Authorized By", "John Doe");
        properties.add("Authorized Date", authDate);
        properties.add("Authorized Revision", doc.getBuiltInDocumentProperties().getRevisionNumber());
        properties.add("Authorized Amount", 123.45);
        
        Assert.assertEquals(true, properties.get("Authorized").toBool());
        Assert.assertEquals("John Doe", properties.get("Authorized By").toString());
        Assert.assertEquals(authDate, properties.get("Authorized Date").toDateTime());
        Assert.assertEquals(1, properties.get("Authorized Revision").toInt());
        Assert.assertEquals(123.45d, properties.get("Authorized Amount").toDouble());