Class XMP.Value

    • Method Detail

      • getType

        public XMP.Type getType()
        Return the Type of this Value. Typically this will match the Type of the XMP.Property that value is stored against, but not always - for example, if an XMP stream is read in where the expected value is a "Seq Text", and the value found is a "Text", then Property.getType() will be "Seq Text" but Value.getType() will be a type that is undefined.
      • getRDFType

        public String getRDFType()

        Structured values in RDF can be stored using a particular element rather than rdf:Description, a format known as "Typed Nodes". This was explicitly disallowed in XMP until 2008, but is allowable as of ISO16684 (XMP 2012). If a structured element is stored as a Typed Node, this method will return the URL of that node, which is defined as the concatenation of the namespace of the element and the localname. For any other type of Value, this returns null.

        Typed nodes are stored as an rdf:type qualifier on the element. So this method is a convenience method for

         Value v = getQualifier(Property.TYPE);
         return v == null ? null : (String)v.getData();
         
      • getData

        public Object getData()
        Return a copy of the data-value of this Value. The returned value will be a simple type - perhaps a String, Boolean, Number, Calendar or some other simple type, or a List of those values (if isList() is true), or a Map where the keys are String and the values are a type returned by this method. Put another way, if this Value contain other Values, the getData() method will be called on those values recursively, to build up a structure.
        Returns:
        the extracted data value, which is an independent copy of the content of this Value.
      • getQualifiers

        public Set<XMP.Property> getQualifiers()
        Return the set of "qualifier" Properties set on this value. Usually this will be an empty Set, as qualifiers are not common in XMP. The one qualifier that is commonly set is the "xml:lang" property, which is a qualifier commonly set on text data.
        See Also:
        XMP.Property.LANG
      • getQualifier

        public XMP.Value getQualifier​(XMP.Property p)
        Return the Value associated with the specified qualifier property on this Value, if set, or null otherwise. For example, to identify the language set on this Value:
          Value langValue = value.getQualifier(Property.LANG);
          String lang = langValue == null ? null : (String)langValue.getData();
         
        See Also:
        getLanguage(), XMP.Property.LANG
      • putQualifier

        public void putQualifier​(XMP.Property p,
                                 XMP.Value value)
        Set a Qualifier on this Value.
        Parameters:
        p - the property
        value - the value, which must be a new Value and not used elsewhere in this (or any other) XMP
      • putQualifier

        public XMP.Value putQualifier​(String name,
                                      Object data)

        Set a Qualifier on this Value. If the specified property is known, this method is identical to the following code:

          Property property = xmp.getProperty(name);
          value.putQualifier(property, property.getType().create(xmp, data));
         

        If the property is not known, it will be created with an undefined type. This allows values to be quickly set on the XMP, although the resulting XMP would not validate against PDF/A-1, 2 or 3, or against a PDF/A-4 Schema.

        Parameters:
        name - the name of the property
        data - the value
      • getLanguage

        public String getLanguage()
        A convenience method to return the "xml:lang" qualifier set on this value, or null if not set. Simply calls
          Value langValue = value.getQualifier(Property.LANG);
          return langValue == null ? null : (String)langValue.getData();
         
      • isList

        public boolean isList()
        Return true if this Value is a list of other Values
      • isMap

        public boolean isMap()
        Return true if this Value is a Map of other Values (also called a "Complex" or "Structured" type)
      • isSimple

        public boolean isSimple()
        Return true if this Value is neither a List or Map.
      • getFields

        public Set<XMP.Property> getFields()
        If this Value is a Map, return a read-only collection of the Fields that are set on this Value. In a completely valid Value, the Fields will be a subset of the XMP.Type.getFields() on this Type, but other Values may have been read in. For non-Map Values, returns an empty set.
      • size

        public int size()
        If this Value is a isList() or isMap(), return the number of Values it contains, otherwise reutrn 0
      • getData

        public Object getData​(int i)
        A convenience method that returns the data from the specified Value. Simply calls:
          Value v = get(i);
          return v == null ? null : v.getData();
         
        Parameters:
        i - the index into the underlying collection
      • getData

        public Object getData​(String key)
        A convenience method that returns the data from the specified Value. Simply calls:
          Value v = get(key);
          return v == null ? null : v.getData();
         
        Parameters:
        key - the key in underlying collection
      • getData

        public Object getData​(XMP.Property key)
        A convenience method that returns the data from the specified Value. Simply calls:
          Value v = get(key);
          return v == null ? null : v.getData();
         
        Parameters:
        key - the key in underlying collection
      • get

        public XMP.Value get​(int i)
        If the Value is a List, return the indexed Value from that List, or null if the value is out of range. If the value is a Map, return the ith entry in the list of keys, otherwise return null. If the Value is a simple Value, return null.
        Parameters:
        i - the index into the underlying collection
      • get

        public XMP.Value get​(XMP.Property key)
        If the Value is a Map, return the Value that matches the specified Property in the underlying map, or null if it doesn't exist. Otherwise, return null.
        Parameters:
        key - the key into the underlying collection
      • get

        public XMP.Value get​(String key)
        If the Value is a Map, return the Value that matches the specified Property in the underlying map, or null if it doesn't exist. As a special case, if the Value is a List then this will return the value that has the specified getLanguage() qualifier set - for example:
         Value value = xmp.get(xmp.getProperty("dc:title"));
         if (value != null) {
             Value defaultTitle = value.get("x-default");
             Value frenchTitle = value.get("fr");
         }
         
        It a List value has no matching language qualifier, or the Type is a simple type, return null.
        Parameters:
        key - the key into the underlying collection
      • set

        public void set​(int i,
                        XMP.Value v)
        Set the value in the underlying Collection, which must be a List.
        Parameters:
        i - the index into the list - set to size() to add an entry to the end of the list
        v - the value to set, which must not be used elsewhere in the XMP. If null, that index is removed from the list
      • set

        public void set​(XMP.Property p,
                        XMP.Value v)
        Set the value in the underlying Collection, which must be a Map. The property should ideally be taken from getType().getFields(), but this is not enforced.
        Parameters:
        p - the Property to use as a key in this Map.
        v - the value to set. If it's null, the value is removed.
      • clone

        public XMP.Value clone​(XMP xmp)
        Make a new deep copy of this Value which is tied to the specified XMP. object. Repairs may be made to the value if the target XMP belongs to PDF that has specific requirements; for example, if the target XMP is on a PDF/A document, undefined fields will be removed.
        Since:
        2.25