GroupDocs.Conversion for Java 20.6 Release Notes

Major Features

There are 20+ features, improvements and bug-fixes in this release, most notable are:

• Legacy API is removed from the product
• Now client application can hookup to converter and monitor for start, progress and complete states
• Improved MPP to spreadsheet conversions
• XML documents can be converted to any format without transformation
• Call ConvertedDocumentStream or ConvertedPageStream delegates providing converted stream for processing or storing.
• Introduced EML to MSG conversions
• API to retrieve prepared default ConvertOptions for desired target conversion
• Introduced GetAllPossibleConversions method which return all supported conversions
• GetPossibleConversions method from a documetn extension without instantiating a Converter
• GetPossibleConversions for currently provided source document
• Improved document info classes

Full List of Issues Covering all Changes in this Release

Public API and Backward Incompatible Changes

1. GroupDocs.Conversion.ConverterSettings.Listener

   Introduced new property Listener

   /**
    * Gets the converter listener implementation used for monitoring conversion status and progress
    * @return The converter listener
    */
   public IConverterListener getListener() {
       return listener;
   }
   
   /**
    * Sets the converter listener implementation used for monitoring conversion status and progress
    * @param listener The converter listener
    */
   public void setListener(IConverterListener listener) {
       this.listener = listener;
   }
   

   ConverterSettings settings = new ConverterSettings();
   settings.setListener(new ConverterListener());
   

   ConverterListener is a class which implement IConverterListener interface:

   public class ConverterListener implements IConverterListener {
      @Override
    public void started() {
         System.out.println("Conversion started...");
      }
   
      @Override
    public void progress(byte current) {
         System.out.println("... "+ current +" % ...");
      }
   
      @Override
    public void completed() {
         System.out.println("... conversion completed");
      }
   }
   

2. GroupDocs.Conversion.Converter.Convert overloads

   Introduced new overloads of Convert method

   /**
    * Converts source document. Saves the whole converted document.
    *
    * @param document output stream
    * @param documentCompleted the delegate that receive converted document stream.
    * @param convertOptions the convert options specific to desired target file type.
    */
   public void convert(final OutputStream document, ConvertedDocumentStream documentCompleted, ConvertOptions convertOptions) {...}
   
   /**
    * Converts source document. Saves the converted document page by page.
    *
    * @param document The delegate that saves converted document page to a stream.
    * @param documentCompleted The delegate that receive converted document page stream.
    * @param convertOptions The convert options specific to desired target file type.
    */
   public void convert(final OutputStream document, ConvertedPageStream documentCompleted, ConvertOptions convertOptions) {...}  
   

   From v20.6 of GroupDocs,Conversion stream created from SaveDocumentStream/SavePageStream delegate is disposed automatically. In order to be able to store converted document stream to file system or database, each time when converted document stream is read the delegates ConvertedDocumentStream/ConvertedPageStream are invoked. 

   String fileName = "source.docx";
   try(FileInputStream fileInputStream = new FileInputStream(fileName)) {
      Converter converter = new Converter(fileInputStream);
   
      ConvertOptions options = new PdfConvertOptions();
      converter.convert(outputStream, new ConvertedDocumentStream() {
         @Override
     public Stream invoke(Stream converted) {
            try(FileOutputStream fileStream = new FileOutputStream("converted.pdf")) {
               converted.copyTo(fileStream);
            } catch (IOException e) {
               ...
            }
            return null;
         }
      }, options);
   
   }
   

3. XML documents can be converted without transformations

   XML document can be converted without transformations

   Converter converter = new Converter("sitemap.xml");
   ConvertOptions options = new PdfConvertOptions();
   converter.convert("converted.pdf", options);
   

4. GroupDocs.Conversion.Contracts.PossibleConversions

   Introduced new class PossibleConversions

   /**
    * Represents a mapping what conversion pairs are supported for specific source file format
    */
   public final class PossibleConversions extends ValueObject {
       public static final PossibleConversions NULL = new PossibleConversions(FileType.Unknown);
   
    /**
    * Creates possible conversion list for specified source file format
    *
    * @param source source file type
    */
    public PossibleConversions(FileType source) {
         ...
    }
   
    /**
    * All target file types and primary/secondary flag
    *
    * @return Iterable of {@link TargetConversion}
    */
    public Iterable<TargetConversion> getAll() {
           ...
    }
   
    /**
    * Returns target conversion for specified target file type
    *
    * @param target target file type
    * @return conversions
    */
    public TargetConversion getTargetConversion(FileType target) {
           ...
    }
   
    /**
    * Returns target conversion for specified target file type extension
    */
    public TargetConversion getTargetConversion(String extension) {
          ...
       }
   
    /**
    * Primary target file types
    *
    * @return primary target file types
    */
    public Iterable<FileType> getPrimary() {
           ...
    }
   
    /**
    * Secondary target file types
    *
    * @return secondary target file types
    */
    public Iterable<FileType> getSecondary() {
           ...
    }
   
   }
   

   Converter converter = new Converter("source.docx");
   PossibleConversions possibleConversions = converter.getPossibleConversions();
   

5. GroupDocs.Conversion.Contracts.TargetConversion

   Introduced new class TargetConversion

   /**
    * Represents possible target conversion and a flag is it a primary or secondary
    */
   public final class TargetConversion {
   
    /**
    * Target document format
    * @return Target document format
    */
    public FileType getFormat() {
           ...
    }
   
    /**
    * Is the conversion primary
    * @return <code>true</code> if primary
    */
    public boolean isPrimary() {
           ...
    }
   
    /**
    * Predefined convert options which could be used to convert to current type
    * @return convert options
    */
    public ConvertOptions getConvertOptions() {
           ...
    }
   } 
   

   Converter converter = new Converter("source.docx");
   PossibleConversions possibleConversions = converter.getPossibleConversions();
   TargetConversion targetConversion = possibleConversions.getTargetConversion("pdf");
   if (targetConversion != null) {
      ConvertOptions convertOptions = targetConversion.getConvertOptions();
   }
   

6. GroupDocs.Conversion.Converter.GetAllPossibleConversions

   Introduced new static method GetAllPossibleConversions in Converter class

   /**
    * Gets all supported conversions
    *
    * @return supported conversions
    */
   public static List<PossibleConversions> getAllPossibleConversions() {
       ...
   }
   

   List<PossibleConversions> allPossibleConversions = Converter.getAllPossibleConversions();
   for (PossibleConversions possibleConversions : allPossibleConversions) {
      System.out.println("Source format:" + possibleConversions.getSource().getDescription());
      for (FileType primary : possibleConversions.getPrimary()) {
         System.out.println("\t-->" + primary.getDescription());
      }
      for (FileType secondary : possibleConversions.getSecondary())
      {
         System.out.println("\t-->" + secondary.getDescription());
      }
   
   }
   

7. GroupDocs.Conversion.Converter.GetPossibleConversions

   Introduced new method GetPossibleConversions in Converter class

   /**
    * Gets all supported conversions
    *
    * @return supported conversions
    */
   public static List<PossibleConversions> getAllPossibleConversions()
   

   Converter converter = new Converter("source.docx");
   PossibleConversions possibleConversions = converter.getPossibleConversions();    
       ...
   

   Introduced new static method GetPossibleConversions in Converter class

   /**
    * Gets supported conversions for provided document extension
    * <example>Converter.GetPossibleConversions(".docx")</example>
    * <example>Converter.GetPossibleConversions("docx")</example>
    *
    * @param extension Document extension
    * @return possible conversions
    */
   public static PossibleConversions getPossibleConversions(String extension)
   

   PossibleConversions possibleConversions = Converter.getPossibleConversions("docx");
   TargetConversion targetConversion = possibleConversions.getTargetConversion("pdf"); // docx -> pdf
   ConvertOptions convertOptions = targetConversion != null ? targetConversion.getConvertOptions() : null;
   

8. GroupDocs.Conversion.Legacy

   We have removed all public types form GroupDocs.Conversion.Legacy namespace.

9. GroupDocs.Conversion.Options.Convert.EmailConvertOptions

   Introduced new class EmailConvertOptions

   /**
    * Options for conversion to Email file type.
    */
   public class EmailConvertOptions extends ConvertOptions<EmailFileType> {
   
   }
   

   Converter converter = new Converter("source.eml");
   ConvertOptions convertOptions = new EmailConvertOptions();
   convertOptions.setFormat(EmailFileType.Msg);
   converter.convert("converted.msg",  convertOptions);
   

10. GroupDocs.Conversion.Options.Load.EmailLoadOptions
    Introduced new property ConvertAttachments in EmailLoadOptions

    //Get option to convert attachments in source email or not. Default: false.
    //@return Option to convert attachments in source email or not. Default: false.   
    public boolean isConvertAttachments() {
        return convertAttachments;
    }

    /**
        * Set option to convert attachments in source email or not
        * @param convertAttachments Option to convert attachments in source email or not.
        */
    public void setConvertAttachments(boolean convertAttachments) {
        this.convertAttachments = convertAttachments;
    }

    String source = "sample-with-attachment.eml";
    EmailLoadOptions loadOptions = new EmailLoadOptions();
    loadOptions.setConvertAttachments(true);
    Converter converter = new Converter(source, loadOptions);
    int index = 1;
    ConvertOptions options = new PdfConvertOptions();
    converter.convert(new FileOutputStream(String.format("converted-%d.pdf", index)), options);