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

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

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");

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");

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

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

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

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

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

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[");

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

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

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