com.itextpdf.kernel.xmp Documentation Differences

iText7 7.1.8 Overview Package Class Text Changes Statistics Help
Generated by
JDiff
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES
com.itextpdf.kernel.xmp Documentation Differences

This file contains all the changes in documentation in the package com.itextpdf.kernel.xmp as colored differences. Deletions are shown ~~like this~~ , and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a tag will cause all subsequent paragraphs to be displayed differently.
 
  
 Class XMPIterator 
  
 
  
 
  
    Interface for the {@code XMPMeta} iteration services. {@code XMPIterator} provides a uniform means to iterate over the schema and properties within an XMP object. 
    The iteration over the schema and properties within an XMP object is very complex. It is helpful to have a thorough understanding of the XMP data tree. One way to learn this is to create some complex XMP and examine the output of {@code XMPMeta#toString}. This is also described in the XMP Specification, in the XMP Data Model chapter.  
    The top of the XMP data tree is a single root node. This does not explicitly appear in the dump and is never visited by an iterator (that is, it is never returned from {@code XMPIterator#next()}). Beneath the root are schema nodes. These are just collectors for top level properties in the same namespace. They are created and destroyed implicitly. Beneath the schema nodes are the property nodes. The nodes below a property node depend on its type (simple, struct, or array) and whether it has qualifiers.  
    An {@code XMPIterator} is created by {@code XMPMeta#interator()} constructor defines a starting point for the iteration and options that control how it proceeds. By default the iteration starts at the root and visits all nodes beneath it in a depth first manner. The root node is not visited, the first visited node is a schema node. You can provide a schema name or property path to select a different starting node. By default this visits the named root node first then all nodes beneath it in a depth first manner.  
    The {@code XMPIterator#next()} method delivers the schema URI, path, and option flags for the node being visited. If the node is simple it also delivers the value. Qualifiers for this node are visited next. The fields of a struct or items of an array are visited after the qualifiers of the parent.  
    The options to control the iteration are:  
    
    JUST_CHILDREN - Visit just the immediate children of the root. Skip the root itself and all nodes below the immediate children. This omits the qualifiers of the immediate children, the qualifier nodes being below what they qualify, default is to visit the complete subtree.  
    JUST_LEAFNODES - Visit just the leaf property nodes and their qualifiers.  
    JUST_LEAFNAME - Return just the leaf component of the node names. The default is to return the full xmp path.  
    OMIT_QUALIFIERS - Do not visit the qualifiers.  
    INCLUDE_ALIASES - Adds known alias properties to the properties in the iteration. Note: Not supported in Java XMPCore! 
       
    
    {@code next()} returns {@code XMPPropertyInfo}-objects and throws a {@code NoSuchElementException} if there are no more properties to return. 
      @since 25.01.2006 
   
  
 Class XMPUtils 
  
 
  
 
  
    Utility methods for XMP. I included only those that are different from the Java default conversion utilities. 
      
   @since 21.02.2006 
  
 Class XMPUtils, void appendProperties(XMPMeta, XMPMeta, boolean, boolean, boolean) 
  
 
  
 
  
    Append properties from one XMP object to another. 
     
   XMPUtils#appendProperties was created to support the File Info dialog's Append button, and has been been generalized somewhat from those specific needs. It appends information from one XMP object (source) to another (dest). The default operation is to append only external properties that do not already exist in the destination. The 
      flag 
    flag  doAllProperties can be used to operate on all properties, external and internal. The flag replaceOldValues option can be used to replace the 
      values 
    values  of existing properties. The notion of external versus internal applies only to top level properties. The keep-or-replace-old notion applies within structs and arrays as described below.  
    
    If replaceOldValues is true then the processing is restricted to the 
       top 
     top  level properties. The processed properties from the source (according 
       to 
     to  doAllProperties) are propagated to the destination, 
      replacing any existing values.Properties in the destination that are not in the 
       source 
     source  are left alone.  
    If replaceOldValues is not passed then the processing is more complicated. 
      Top level properties are added to the destination if they do not already exist. 
      If they do exist but differ in form (simple/struct/array) then the destination is left alone. If the forms match, simple properties are left unchanged while structs and arrays are merged. 
        
    If deleteEmptyValues is passed then an empty value in the source XMP causes the corresponding destination XMP property to be deleted. The default is to treat 
       empty 
     empty  values the same as non-empty values. An empty value is any of a simple empty string, an array with no items, or a struct with no fields. Qualifiers are ignored.  
   
 
     
   The detailed behavior is defined by the following pseudo-code:  
    
        appendProperties ( sourceXMP, destXMP, doAllProperties, 
     
     
     
     
     
    			replaceOldValues, deleteEmptyValues ):
       for all source schema (top level namespaces):
          for all top level properties in sourceSchema:
             if doAllProperties or prop is external:
                appendSubtree ( sourceNode, destSchema, replaceOldValues, deleteEmptyValues )
 

     
     
     
     
     

    appendSubtree ( sourceNode, destParent, replaceOldValues, deleteEmptyValues ):
        if deleteEmptyValues and source value is empty:
            delete the corresponding child from destParent
        else if sourceNode not in destParent (by name):
           copy sourceNode's subtree to destParent
        else if replaceOld:
            delete subtree from destParent
            copy sourceNode's subtree to destParent
        else:
            // Already exists in dest and not replacing, merge structs and arrays
            if sourceNode and destNode forms differ:
                return, leave the destNode alone
            else if form is a struct:
                for each field in sourceNode:
                    AppendSubtree ( sourceNode.field, destNode, replaceOldValues )
            else if form is an alt-text array:
                copy new items by "xml:lang" value into the destination
            else if form is an array:
                copy new items by value into the destination, ignoring order and duplicates
  
    
   Note: appendProperties can be expensive if replaceOldValues is not passed 
      and 
    and  the XMP contains large arrays. The array item checking described above is n-squared. 
     Each source item is checked to see if it already exists in the destination, 
     without regard to order or duplicates.  
   Simple items are compared by value and "xml:lang" qualifier, other qualifiers are ignored. Structs are recursively compared by field names, without regard to field order. Arrays are compared by recursively comparing all items. @param source The source XMP object. @param dest The destination XMP object. @param doAllProperties Do internal properties in addition to external properties. @param replaceOldValues Replace the values of existing properties. @param deleteEmptyValues Delete destination values if source property is empty. @throws XMPException Forwards the Exceptions from the metadata processing 
  
 Class XMPUtils, String catenateArrayItems(XMPMeta, String, String, String, String, boolean) 
  
 
  
 
  
    Create a single edit string from an array of strings. 
     @param xmp The XMP object containing the array to be catenated. @param schemaNS The schema namespace URI for the array. Must not be null or the empty string. @param arrayName The name of the array. May be a general path expression, must not be null or the empty string. Each item in the array must be a simple string value. @param separator The string to be used to separate the items in the catenated string. Defaults to "; ", ASCII semicolon and space (U+003B, U+0020). @param quotes The characters to be used as quotes around array items that contain a separator. Defaults to '"' @param allowCommas Option flag to control the catenation. @return Returns the string containing the catenated array items. @throws XMPException Forwards the Exceptions from the metadata processing 
  
 Class XMPUtils, String convertFromBoolean(boolean) 
  
 
  
 
  
    Convert from boolean to string. 
      
   @param value a boolean value @return The XMP string representation of the boolean. The values used are given by the constnts XMPConst.TRUESTR and XMPConst.FALSESTR. 
  
 Class XMPUtils, String convertFromDate(XMPDateTime) 
  
 
  
 
  
    Convert from XMPDateTime to string. 
     @param value an XMPDateTime @return The string representation of the long. 
  
 Class XMPUtils, String convertFromDouble(double) 
  
 
  
 
  
    Convert from long to string. 
      
   @param value a long value @return The string representation of the long. 
  
 Class XMPUtils, String convertFromInteger(int) 
  
 
  
 
  
    Convert from int to string. 
      
   @param value an int value @return The string representation of the int. 
  
 Class XMPUtils, String convertFromLong(long) 
  
 
  
 
  
    Convert from long to string. 
      
   @param value a long value @return The string representation of the long. 
  
 Class XMPUtils, boolean convertToBoolean(String) 
  
 
  
 
  
    Convert from string to Boolean. 
     @param value The string representation of the Boolean. @return The appropriate boolean value for the string. The checked values for true and false are: 
    
    XMPConst.TRUESTR and XMPConst.FALSESTR  
    "t" and "f"  
    "on" and "off"  
    "yes" and "no"  
    "value <> 0" and "value == 0"  
    @throws XMPException If an empty string is passed. 
  
 Class XMPUtils, XMPDateTime convertToDate(String) 
  
 
  
 
  
    Converts a string value to an XMPDateTime. 
     @param rawValue the string value @return Returns an XMPDateTime-object. @throws XMPException If the rawValue is null or empty or the conversion fails. 
  
 Class XMPUtils, double convertToDouble(String) 
  
 
  
 
  
    Converts a string value to a double. 
     @param rawValue the string value @return Returns a double. @throws XMPException If the rawValue is null or empty or the conversion fails. 
  
 Class XMPUtils, int convertToInteger(String) 
  
 
  
 
  
    Converts a string value to an int. 
     @param rawValue the string value @return Returns an int. @throws XMPException If the rawValue is null or empty or the conversion fails. 
  
 Class XMPUtils, long convertToLong(String) 
  
 
  
 
  
    Converts a string value to a long. 
     @param rawValue the string value @return Returns a long. @throws XMPException If the rawValue is null or empty or the conversion fails. 
  
 Class XMPUtils, byte[] decodeBase64(String) 
  
 
  
 
  
    Decode from Base64 encoded string to raw data. 
     @param base64String a base64 encoded string @return Returns a byte array containg the decoded string. @throws XMPException Thrown if the given string is not property base64 encoded 
  
 Class XMPUtils, String encodeBase64(byte[]) 
  
 
  
 
  
    Convert from a byte array to a base64 encoded string. 
      
   @param buffer the byte array to be converted @return Returns the base64 string. 
  
 Class XMPUtils, void removeProperties(XMPMeta, String, String, boolean, boolean) 
  
 
  
 
  
    Remove multiple properties from an XMP object. 
     RemoveProperties was created to support the File Info dialog's Delete button, and has been been generalized somewhat from those specific needs. It operates in one of three main modes depending on the schemaNS and propName parameters: 
      
    
    
     Non-empty schemaNS and propName - The named property is removed if it is an external property, or if 
       the 
     the  flag doAllProperties option is true. It does not matter whether the named property is an actual property or an alias. 
        
     Non-empty schemaNS and empty propName - The all external properties in the named schema are removed. Internal properties are also removed if the flag doAllProperties option is set. In addition, aliases from the named schema will be removed if the flag includeAliases 
      option is set. 
        
     Empty schemaNS and empty propName - All external properties in all schema are removed. Internal properties are also removed if 
       the 
     the  flag doAllProperties option is passed. Aliases are implicitly handled because the associated actuals are internal if the alias is.  
   
 
     It is an error to pass an empty schemaNS and non-empty propName. 
     @param xmp The XMP object containing the properties to be removed. 
     @param schemaNS Optional schema namespace URI for the properties to be removed. 
     @param propName Optional path expression for the property to be removed. 
     @param doAllProperties Option flag to control the deletion: do internal properties in addition to external properties. 
      
   @param includeAliases Option flag to control the deletion: 
    Include aliases in the "named schema" case above. Note: Currently not supported. @throws XMPException Forwards the Exceptions from the metadata processing 
  
 Class XMPUtils, void separateArrayItems(XMPMeta, String, String, String, PropertyOptions, boolean) 
  
 
  
 
  
    Separate a single edit string into an array of strings. 
     @param xmp The XMP object containing the array to be updated. @param schemaNS The schema namespace URI for the array. Must not be null or the empty string. @param arrayName The name of the array. May be a general path expression, must not be null or the empty string. Each item in the array must be a simple string value. @param catedStr The string to be separated into the array items. @param arrayOptions Option flags to control the separation. 
    @param preserveCommas Flag if commas shall be preserved @throws XMPException Forwards the Exceptions from the metadata processing