Metadata (GroupDocs.Metadata (26.1) API Reference)

java.lang.Object
- com.groupdocs.metadata.Metadata

All Implemented Interfaces:

Closeable, AutoCloseable
```
public final class Metadata
extends Object
implements Closeable
```
Provides the main class to access metadata in all supported formats.

Constructor Summary

Constructors
Constructor and Description
`Metadata(InputStream document)` Initializes a new instance of the `Metadata` class.
`Metadata(InputStream document, LoadOptions loadOptions)` Initializes a new instance of the `Metadata` class.
`Metadata(String filePath)` Initializes a new instance of the `Metadata` class.
`Metadata(String filePath, LoadOptions loadOptions)` Initializes a new instance of the `Metadata` class.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`addProperties(Specification specification, PropertyValue value)` Adds known metadata properties satisfying the specification.
`void`	`close()` Closes the loaded document and releases any system resources associated with it.
`void`	`copyTo(MetadataPackage metadataPackage)` Copy known metadata properties from source package to destination package.
`int`	`copyTo(MetadataPackage metadataPackage, List<PropertyTag> tags)` Copy known metadata properties from source package to destination package.
`IReadOnlyList<MetadataProperty>`	`findProperties(Specification specification)` Finds the metadata properties satisfying a specification.
`void`	`generatePreview(PreviewOptions previewOptions)` Creates preview images for specified pages.
`IDocumentInfo`	`getDocumentInfo()` Gets common information about the loaded document.
`FileFormat`	`getFileFormat()` Gets the type of the loaded file (if recognized).
`RootMetadataPackage`	`getRootPackage()` Gets the root package providing access to all metadata properties extracted from the file.
`<TRoot extends RootMetadataPackage> TRoot`	`getRootPackageGeneric()` Gets the root package providing access to all metadata properties extracted from the file.
`int`	`removeProperties(Specification specification)` Removes metadata properties satisfying a specification.
`int`	`sanitize()` Removes writable metadata properties from all detected packages or whole packages if possible.
`void`	`save()` Saves all changes made in the loaded document.
`void`	`save(OutputStream document)` Saves the document content into a stream.
`void`	`save(String filePath)` Saves the document content to the specified file.
`int`	`setProperties(Specification specification, PropertyValue value)` Sets known metadata properties satisfying the specification.
`int`	`updateProperties(Specification specification, PropertyValue value)` Updates known metadata properties satisfying a specification.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail
- Metadata
```
public Metadata(InputStream document)
```
  Initializes a new instance of the Metadata class.
  Parameters:
  document - A stream that contains the document to load.
  Learn more
  This example demonstrates how to load a file from a stream.
  // Constants.InputDoc is an absolute or relative path to your document. Ex: @"C:\Docs\source.doc" try (InputStream stream = new FileInputStream(Constants.InputDoc)) { try (Metadata metadata = new Metadata(stream)) { // Extract, edit or remove metadata here } }
- Metadata
```
public Metadata(InputStream document,
                LoadOptions loadOptions)
```
  Initializes a new instance of the Metadata class.
  Parameters:
  
  document - A stream that contains the document to load.
  loadOptions - Additional options to use when loading a document.
  Learn more
- Metadata
```
public Metadata(String filePath)
```
  Initializes a new instance of the Metadata class.
  Parameters:
  filePath - A string that contains the full name of the file from which to create a Metadata instance.
  Learn more
  This example demonstrates how to load a file from a local disk.
  // Constants.InputOne is an absolute or relative path to your document. Ex: @"C:\Docs\source.one" try (Metadata metadata = new Metadata(Constants.InputOne)) { // Extract, edit or remove metadata here }
- Metadata
```
public Metadata(String filePath,
                LoadOptions loadOptions)
```
  Initializes a new instance of the Metadata class.
  Parameters:
  
  filePath - A string that contains the full name of the file from which to create a Metadata instance.
  loadOptions - Additional options to use when loading a document.
  Learn more
  This example demonstrates how to load a password-protected document.
  // Specify the password LoadOptions loadOptions = new LoadOptions(); loadOptions.setPassword("123"); // Constants.ProtectedDocx is an absolute or relative path to your document. Ex: @"C:\Docs\source.docx" try (Metadata metadata = new Metadata(Constants.ProtectedDocx, loadOptions)) { // Extract, edit or remove metadata here }

Method Detail

addProperties

public final int addProperties(Specification specification,
                               PropertyValue value)

Adds known metadata properties satisfying the specification. The operation is recursive so it affects all nested packages as well.

Parameters:

specification - A specification to test each metadata property for a condition.

value - A value for the picked properties.

Learn more

More examples demonstrating usages of this method: Adding metadata

This example demonstrates how to add some missing metadata properties to a file regardless of its format.


 File folder = new File(Constants.InputPath);
 for (File file : folder.listFiles()) {
     try (Metadata metadata = new Metadata(file.getAbsolutePath())) {
         if (metadata.getFileFormat() != FileFormat.Unknown && !metadata.getDocumentInfo().isEncrypted()) {
             System.out.println();
             System.out.println(file.getName());
             // Add a property containing the file last printing date if it's missing
             // Note that the property will be added to metadata packages that satisfy the following criteria:
             // 1) Only existing metadata packages will be affected. No new packages are added during this operation
             // 2) There should be a known metadata property in the package structure that fits the search condition but is actually missing in the package.
             // All properties supported by a certain package are usually defined in the specification of a particular metadata standard
             int affected = metadata.addProperties(new ContainsTagSpecification(Tags.getTime().getPrinted()), new PropertyValue(new Date()));
             System.out.println(String.format("Affected properties: %s", affected));
             metadata.save(Constants.OutputPath + "output." + FilenameUtils.getExtension(file.getName()));
         }
     }
 }

Returns:

The number of affected properties.

close
```
public void close()
```
Closes the loaded document and releases any system resources associated with it.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

copyTo

public void copyTo(MetadataPackage metadataPackage)

Copy known metadata properties from source package to destination package. The operation is recursive so it affects all nested packages as well. If an existing property its value is updated. If there is a known property missing in a destination package it is added to the package. If there is a known property missing in a source package it is not remove from destination package. If that need, use Sanitize method before.

 This example demonstrates how to copy metadata properties from source package to destination package.
  Metadata source_metadata = new Metadata(Constants.InputPdf);
 Metadata destination_metadata = new Metadata(Constants.DestinationPdf);
 {
     source_metadata.copyTo(destination_metadata);
     source_metadata.save();
 }

Parameters:: metadataPackage - A destination metadata package.
If the package types do not match, an error will be returned.

copyTo

public int copyTo(MetadataPackage metadataPackage,
                  List<PropertyTag> tags)

 This example demonstrates how to copy metadata properties from source package to destination package.
  Metadata source_metadata = new Metadata(Constants.InputPdf);
 Metadata destination_metadata = new Metadata(Constants.DestinationPdf);
 {
     List<PropertyTag> tags = new ArrayList<PropertyTag>();
     tags.add(Tags.getPerson().getCreator());
     source_metadata.copyTo(destination_metadata, tags);
     source_metadata.save();
 }

Parameters:: metadataPackage - A destination metadata package.; tags - A list of the tags.
If the package types do not match, an error will be returned.
Returns:: The number of affected properties.

findProperties

public final IReadOnlyList<MetadataProperty> findProperties(Specification specification)

Finds the metadata properties satisfying a specification. The search is recursive so it affects all nested packages as well.

Parameters:

specification - A function to test each metadata property for a condition.

Learn more

More examples demonstrating usages of this method: Extracting metadata

This example demonstrates how to search for specific metadata properties using tags.


 // Constants.InputPptx is an absolute or relative path to your document. Ex: @"C:\Docs\source.pptx"
 try (Metadata metadata = new Metadata(Constants.InputPptx)) {
     // Fetch all the properties satisfying the predicate:
     // property contains the name of the last document editor OR the date/time the document was last modified
     IReadOnlyList<MetadataProperty> properties = metadata.findProperties(
             new ContainsTagSpecification(Tags.getPerson().getEditor()).or(new ContainsTagSpecification(Tags.getTime().getModified())));
     for (MetadataProperty property : properties) {
         System.out.println(String.format("Property name: %s, Property value: %s", property.getName(), property.getValue()));
     }
 }

Returns:

A collection that contains properties from the package that satisfy the condition.

generatePreview
```
public final void generatePreview(PreviewOptions previewOptions)
```
Creates preview images for specified pages.
Parameters:
previewOptions - A set of options for preview generation.
Learn more
- Generate document preview

getDocumentInfo
```
public final IDocumentInfo getDocumentInfo()
```
Gets common information about the loaded document.
Returns:
An object representing common document information.
Learn more
- Get document info

getFileFormat
```
public final FileFormat getFileFormat()
```
Gets the type of the loaded file (if recognized).

Returns:

The type of the loaded file if recognized; otherwise, F:GroupDocs.Metadata.FileFormat.Unknown.

getRootPackage

public final RootMetadataPackage getRootPackage()

Gets the root package providing access to all metadata properties extracted from the file.

Returns:

The root package providing access to all metadata properties extracted from the file.

Learn more

Traverse a whole metadata tree

This example demonstrates how to traverse the whole metadata tree for a specific file regardless of the format.


 public static void run() {
     try (Metadata metadata = new Metadata(Constants.JpegWithXmp)) {
         displayMetadataTree(metadata.getRootPackage(), 0);
     }
 }
 private static void displayMetadataTree(MetadataPackage metadata, int indent) {
     if (metadata != null) {
         String stringMetadataType = String.valueOf(metadata.getMetadataType());
         System.out.printf("%" + (stringMetadataType.length() + indent) + "s%n", stringMetadataType);
         for (MetadataProperty property : metadata) {
             String stringPropertyRepresentation = "Name: " + property.getName() + ", Value: " + property.getValue();
             System.out.printf("%" + (stringPropertyRepresentation.length() + indent + 1) + "s%n", stringPropertyRepresentation);
             if (property.getValue() != null) {
                 switch (property.getValue().getType()) {
                     case MetadataPropertyType.Metadata:
                         displayMetadataTree(property.getValue().toClass(MetadataPackage.class), indent + 2);
                     break;
                     case MetadataPropertyType.MetadataArray:
                         displayMetadataTree(property.getValue().toArray(MetadataPackage.class), indent + 2);
                     break;
                 }
             }
         }
     }
 }
 private static void displayMetadataTree(MetadataPackage[] metadataArray, int indent) {
     if (metadataArray != null) {
         for (MetadataPackage metadata : metadataArray) {
             displayMetadataTree(metadata, indent);
         }
     }
 }

getRootPackageGeneric
```
public final <TRoot extends RootMetadataPackage> TRoot getRootPackageGeneric()
```
Gets the root package providing access to all metadata properties extracted from the file.

Learn more
- Traverse a whole metadata tree
Returns:

The root package providing access to all metadata properties extracted from the file.
TRoot: The exact type of the root package.

removeProperties

public final int removeProperties(Specification specification)

Removes metadata properties satisfying a specification.

Parameters:

specification - A specification to test each metadata property for a condition.

Learn more

More examples demonstrating usages of this method: Removing metadata

This example demonstrates how to remove specific metadata properties using various criteria.


 public class RemoveMetadataProperties {
     public static void run() {
         // Constants.InputDocx is an absolute or relative path to your document. Ex: @"C:\Docs\source.docx"
         try (Metadata metadata = new Metadata(Constants.InputDocx)) {

             // Remove all the properties satisfying the predicate:
             // property contains the name of the document author OR
             // it refers to the last editor OR
             // the property value is a string that is equal to the given string "John" (to remove any mentions of John from the detected metadata)
             int affected = metadata.removeProperties(
                     new ContainsTagSpecification(Tags.getPerson().getCreator()).or(
                             new ContainsTagSpecification(Tags.getPerson().getEditor())).or(
                             new OfTypeSpecification(MetadataPropertyType.String).and(new RemoveMetadataProperties().new WithValueSpecification("John"))));

             System.out.println(String.format("Properties removed: %s", affected));

             metadata.save(Constants.OutputDocx);
         }
     }

     // Define your own specifications to filter metadata properties
     public class WithValueSpecification extends Specification {
         public WithValueSpecification(Object value) {
             setValue(value);
         }

         public final Object getValue() {
             return auto_Value;
         }

         private void setValue(Object value) {
             auto_Value = value;
         }

         private Object auto_Value;

         public boolean isSatisfiedBy(MetadataProperty candidate) {
             return candidate.getValue().getRawValue().equals(getValue());
         }
     }
 }

Returns:

The number of affected properties.

sanitize

public final int sanitize()

Removes writable metadata properties from all detected packages or whole packages if possible. The operation is recursive so it affects all nested packages as well.

Returns:

The number of affected properties.

Learn more

More examples demonstrating usages of this method: Clean metadata

This example demonstrates how to remove all detected metadata packages/properties from a file.


 // Constants.InputPdf is an absolute or relative path to your document. Ex: @"C:\Docs\source.pdf"
 try (Metadata metadata = new Metadata(Constants.InputPdf)) {
     // Remove detected metadata packages
     int affected = metadata.sanitize();
     System.out.println(String.format("Properties removed: %s", affected));
     metadata.save(Constants.OutputPdf);
 }

save

public final void save()

Saves all changes made in the loaded document.

Learn more

This example shows how to save the modified content to the underlying file.


 // Constants.InputPpt is an absolute or relative path to your document. Ex: @"C:\Docs\test.ppt"
 File outputFile = new File(Constants.OutputPpt);
 outputFile.delete();
 Files.copy(new File(Constants.InputPpt).toPath(), outputFile.toPath());
 try (Metadata metadata = new Metadata(Constants.OutputPpt)) {
     // Edit or remove metadata here
     // Saves the document to the underlying file
     metadata.save();
 }

save

public final void save(OutputStream document)

Saves the document content into a stream.

Parameters:

document - An output stream for the document.

Learn more

This example shows how to save a document to the specified stream.


 try (OutputStream stream = new FileOutputStream(Constants.OutputPng)) {
     // Constants.InputPng is an absolute or relative path to your document. Ex: @"C:\Docs\test.png"
     try (Metadata metadata = new Metadata(Constants.InputPng)) {
         // Edit or remove metadata here
         metadata.save(stream);
     }
 }

save
```
public final void save(String filePath)
```
Saves the document content to the specified file.
Parameters:
filePath - The full name of the output file.
Learn more
This example shows how to save a document to the specified location.
```
 // Constants.InputJpeg is an absolute or relative path to your document. Ex: @"C:\Docs\test.jpg"
 try (Metadata metadata = new Metadata(Constants.InputJpeg)) {
     // Edit or remove metadata here
     metadata.save(Constants.OutputJpeg);
 }
 
```

setProperties
```
public final int setProperties(Specification specification,
                               PropertyValue value)
```
Sets known metadata properties satisfying the specification. The operation is recursive so it affects all nested packages as well. This method is a combination of AddProperties and UpdateProperties. If an existing property satisfies the specification its value is updated. If there is a known property missing in the package that satisfies the specification it is added to the package.
Parameters:

specification - A specification to test each metadata property for a condition.
value - A new value for the filtered properties.
Please note that GroupDocs.Metadata implicitly checks the type of each filtered property. It's impossible to set a property with a value having inappropriate type.

Learn more
- More examples demonstrating usages of this method: Set metadata properties
This example demonstrates how to set specific metadata properties using different criteria.
```
 // Constants.InputVsdx is an absolute or relative path to your document. Ex: @"C:\Docs\source.vsdx"
 try (Metadata metadata = new Metadata(Constants.InputVsdx)) {
     // Set the value of each property that satisfies the predicate:
     // property contains the date/time the document was created OR modified
     int affected = metadata.setProperties(
             new ContainsTagSpecification(Tags.getTime().getCreated()).or(new ContainsTagSpecification(Tags.getTime().getModified())),
             new PropertyValue(new Date()));
     System.out.println(String.format("Properties set: %s", affected));
     metadata.save(Constants.OutputVsdx);
 }
 
```
Returns:

The number of affected properties.

updateProperties

public final int updateProperties(Specification specification,
                                  PropertyValue value)

Updates known metadata properties satisfying a specification. The operation is recursive so it affects all nested packages as well.

Parameters:

specification - A specification to test each metadata property for a condition.

value - A new value for the filtered properties.

Please note that GroupDocs.Metadata implicitly checks the type of each filtered property. It's impossible to update a property with a value having an inappropriate type.

Learn more

More examples demonstrating usages of this method: Updating metadata

This example demonstrates how to update existing metadata properties by various criteria regardless of the file format.


 public class UpdatingMetadata {
     public static void run() {
         Date threeDaysAgo = new Date(System.currentTimeMillis() - TimeUnit.DAYS.toMillis(3));
         File folder = new File(Constants.InputPath);
         for (File file : folder.listFiles()) {
             try (Metadata metadata = new Metadata(file.getAbsolutePath())) {
                 if (metadata.getFileFormat() != FileFormat.Unknown && !metadata.getDocumentInfo().isEncrypted()) {
                     System.out.println();
                     System.out.println(file.getName());
                     // Update the file creation date/time if the existing value is older than 3 days
                     int affected = metadata.updateProperties(new ContainsTagSpecification(Tags.getTime().getCreated()).and(
                             new OfTypeSpecification(MetadataPropertyType.DateTime)).and(
                             new UpdatingMetadata().new DateBeforeSpecification(threeDaysAgo)), new PropertyValue(new Date()));
                     System.out.println(String.format("Affected properties: %s", affected));
                     metadata.save(Constants.OutputPath + "output." + FilenameUtils.getExtension(file.getName()));
                 }
             }
         }
     }
     // Define your own specifications to filter metadata properties
     public class DateBeforeSpecification extends Specification {
         public DateBeforeSpecification(Date date) {
             setValue(date);
         }

         public final Date getValue() {
             return auto_Value;
         }

         private void setValue(Date value) {
             auto_Value = value;
         }

         private Date auto_Value;

         public boolean isSatisfiedBy(MetadataProperty candidate) {
             Date date = candidate.getValue().toClass(Date.class);
             if (date != null) {
                 return date.before(getValue());
             }
             return false;
         }
     }
 }

Returns:

The number of affected properties.

Class Metadata

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Metadata

Metadata

Metadata

Metadata

Method Detail

addProperties

close

copyTo

copyTo

findProperties

generatePreview

getDocumentInfo

getFileFormat

getRootPackage

getRootPackageGeneric

removeProperties

sanitize

save

save

save

setProperties

updateProperties