com.groupdocs.metadata

Constructor Detail

• 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

  • Load from a local disk
  • Load from a stream
  • Load a file of a specific format
  • Load a password-protected document

  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(InputStream document)

  Initializes a new instance of the Metadata class.

  Parameters:

  document - A stream that contains the document to load.

  Learn more

  • Load from a local disk
  • Load from a stream
  • Load a file of a specific format
  • Load a password-protected document

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

  • Load from a local disk
  • Load from a stream
  • Load a file of a specific format
  • Load a password-protected document

  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
   }
   

• 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

  • Load from a local disk
  • Load from a stream
  • Load a file of a specific format
  • Load a password-protected document

Method Detail

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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

  • Save a modified file to the original source
  • Save a modified file to a specified location
  • Save a modified file to a stream

  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

  • Save a modified file to the original source
  • Save a modified file to a specified location
  • Save a modified file to a stream

  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

  • Save a modified file to the original source
  • Save a modified file to a specified location
  • Save a modified file to a stream

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

• 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

• 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