public class DocumentProperty
extends java.lang.Object
implements java.lang.Cloneable
To learn more, visit the Work with Document Properties documentation article.
DocumentPropertyCollection| Modifier and Type | Method and Description |
|---|---|
java.lang.String |
getLinkSource()
Gets the source of a linked custom document property.
|
java.lang.String |
getName()
Returns the name of the property.
|
int |
getType()
Gets the data type of the property.
|
java.lang.Object |
getValue()
Gets the value of the property.
|
boolean |
isLinkToContent()
Shows whether this property is linked to content or not.
|
protected java.lang.Object |
memberwiseClone() |
void |
setValue(java.lang.Object value)
Sets the value of the property.
|
boolean |
toBool()
Returns the property value as bool.
|
byte[] |
toByteArray()
Returns the property value as byte array.
|
java.util.Date |
toDateTime()
Returns the property value as DateTime in UTC.
|
double |
toDouble()
Returns the property value as double.
|
int |
toInt()
Returns the property value as integer.
|
java.lang.String |
toString()
Returns the property value as a string formatted according to the current locale.
|
public java.lang.String getName()
Remarks:
Cannot be null and cannot be an empty string.
public java.lang.Object getValue()
Remarks:
Cannot be null.
public void setValue(java.lang.Object value)
Remarks:
Cannot be null.
value - The value of the property.public int getType()
Examples:
Shows how to work with a document's custom properties.
Document doc = new Document();
CustomDocumentProperties properties = doc.getCustomDocumentProperties();
Assert.assertEquals(0, properties.getCount());
// Custom document properties are key-value pairs that we can add to the document.
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);
// The collection sorts the custom properties in alphabetic order.
Assert.assertEquals(1, properties.indexOf("Authorized Amount"));
Assert.assertEquals(5, properties.getCount());
// Print every custom property in the document.
Iterator<DocumentProperty> enumerator = properties.iterator();
while (enumerator.hasNext()) {
DocumentProperty property = enumerator.next();
System.out.println(MessageFormat.format("Name: \"{0}\"\n\tType: \"{1}\"\n\tValue: \"{2}\"", property.getName(), property.getType(), property.getValue()));
}
// Display the value of a custom property using a DOCPROPERTY field.
DocumentBuilder builder = new DocumentBuilder(doc);
FieldDocProperty field = (FieldDocProperty) builder.insertField(" DOCPROPERTY \"Authorized By\"");
field.update();
Assert.assertEquals("John Doe", field.getResult());
// We can find these custom properties in Microsoft Word via "File" -> "Properties" > "Advanced Properties" > "Custom".
doc.save(getArtifactsDir() + "DocumentProperties.DocumentPropertyCollection.docx");
// Below are three ways or removing custom properties from a document.
// 1 - Remove by index:
properties.removeAt(1);
Assert.assertFalse(properties.contains("Authorized Amount"));
Assert.assertEquals(4, properties.getCount());
// 2 - Remove by name:
properties.remove("Authorized Revision");
Assert.assertFalse(properties.contains("Authorized Revision"));
Assert.assertEquals(3, properties.getCount());
// 3 - Empty the entire collection at once:
properties.clear();
Assert.assertEquals(0, properties.getCount());
PropertyType constants.public java.lang.String getLinkSource()
Examples:
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("Hello world!");
builder.endBookmark("MyBookmark");
// Link a new custom property to a bookmark. The value of this property
// will be the contents of the bookmark that it references in the "LinkSource" member.
CustomDocumentProperties customProperties = doc.getCustomDocumentProperties();
DocumentProperty customProperty = customProperties.addLinkToContent("Bookmark", "MyBookmark");
Assert.assertEquals(true, customProperty.isLinkToContent());
Assert.assertEquals("MyBookmark", customProperty.getLinkSource());
Assert.assertEquals("Hello world!", customProperty.getValue());
doc.save(getArtifactsDir() + "DocumentProperties.LinkCustomDocumentPropertiesToBookmark.docx");
public boolean isLinkToContent()
Examples:
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("Hello world!");
builder.endBookmark("MyBookmark");
// Link a new custom property to a bookmark. The value of this property
// will be the contents of the bookmark that it references in the "LinkSource" member.
CustomDocumentProperties customProperties = doc.getCustomDocumentProperties();
DocumentProperty customProperty = customProperties.addLinkToContent("Bookmark", "MyBookmark");
Assert.assertEquals(true, customProperty.isLinkToContent());
Assert.assertEquals("MyBookmark", customProperty.getLinkSource());
Assert.assertEquals("Hello world!", customProperty.getValue());
doc.save(getArtifactsDir() + "DocumentProperties.LinkCustomDocumentPropertiesToBookmark.docx");
boolean value.public java.lang.String toString()
Remarks:
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().
Examples:
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());
Shows how to work with custom document properties.
Document doc = new Document(getMyDir() + "Properties.docx");
// Every document contains a collection of custom properties, which, like the built-in properties, are key-value pairs.
// The document has a fixed list of built-in properties. The user creates all of the custom properties.
Assert.assertEquals("Value of custom document property", doc.getCustomDocumentProperties().get("CustomProperty").toString());
doc.getCustomDocumentProperties().add("CustomProperty2", "Value of custom document property #2");
System.out.println("Custom Properties:");
for (DocumentProperty customDocumentProperty : doc.getCustomDocumentProperties()) {
System.out.println(customDocumentProperty.getName());
System.out.println(MessageFormat.format("\tType:\t{0}", customDocumentProperty.getType()));
System.out.println(MessageFormat.format("\tValue:\t\"{0}\"", customDocumentProperty.getValue()));
}
toString in class java.lang.Objectpublic int toInt()
Remarks:
Throws an exception if the property type is not PropertyType.NUMBER.
Examples:
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 double toDouble()
Remarks:
Throws an exception if the property type is not PropertyType.NUMBER.
Examples:
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.util.Date toDateTime()
Remarks:
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.
Examples:
Shows how to create a custom document property which contains a date and time.
Document doc = new Document();
doc.getCustomDocumentProperties().add("AuthorizationDate", new Date());
System.out.println(MessageFormat.format("Document authorized on {0}", doc.getCustomDocumentProperties().get("AuthorizationDate")));
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 boolean toBool()
Remarks:
Throws an exception if the property type is not PropertyType.BOOLEAN.
Examples:
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()
Remarks:
Throws an exception if the property type is not PropertyType.BYTE_ARRAY.
Examples:
Shows how to add a thumbnail to a document that we save as an Epub.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world!");
// If we save a document, whose "Thumbnail" property contains image data that we added, as an Epub,
// a reader that opens that document may display the image before the first page.
BuiltInDocumentProperties properties = doc.getBuiltInDocumentProperties();
byte[] thumbnailBytes = DocumentHelper.getBytesFromStream(new FileInputStream(getImageDir() + "Logo.jpg"));
properties.setThumbnail(thumbnailBytes);
doc.save(getArtifactsDir() + "DocumentProperties.Thumbnail.epub");
// We can extract a document's thumbnail image and save it to the local file system.
DocumentProperty thumbnail = doc.getBuiltInDocumentProperties().get("Thumbnail");
FileUtils.writeByteArrayToFile(new File(getArtifactsDir() + "DocumentProperties.Thumbnail.gif"), thumbnail.toByteArray());
protected java.lang.Object memberwiseClone()