docs: @Nullable
      public Integer getInteger(int tagType)
      {
          Object o = getObject(tagType);
  
          if (o == null)
              return null;
  
          if (o instanceof Number) {
              return ((Number)o).intValue();
          } else if (o instanceof String || o instanceof StringValue) {
              try {
                  return Integer.parseInt(o.toString());
              } catch (NumberFormatException nfe) {
                  // convert the char array to an int
                  String s = o.toString();
                  byte[] bytes = s.getBytes();
                  long val = 0;
                  for (byte aByte : bytes) {
                      val = val << 8;
                      val += (aByte & 0xff);
                  }
                  return (int)val;
              }
          } else if (o instanceof Rational[]) {
              Rational[] rationals = (Rational[])o;
              if (rationals.length == 1)
                  return rationals[0].intValue();
          } else if (o instanceof byte[]) {
              byte[] bytes = (byte[])o;
              if (bytes.length == 1)
                  return (int)bytes[0];
          } else if (o instanceof int[]) {
              int[] ints = (int[])o;
              if (ints.length == 1)
                  return ints[0];
          } else if (o instanceof short[]) {
              short[] shorts = (short[])o;
              if (shorts.length == 1)
                  return (int)shorts[0];
          }
          return null;
      }
  
      /**
       * Gets the specified tag's value as a String array, if possible.  Only supported
       * where the tag is set as StringValue[], String[], StringValue, String, int[], byte[] or Rational[].
       *
       * @param tagType the tag identifier
       * @return the tag's value as an array of Strings. If the value is unset or cannot be converted, <code>null</code> is returned.
       */
      @Nullable
      public String[] getStringArray(int tagType)
      {
          Object o = getObject(tagType);
          if (o == null)
              return null;
          if (o instanceof String[])
              return (String[])o;
          if (o instanceof String)
              return new String[] { (String)o };
          if (o instanceof StringValue)
              return new String[] { o.toString() };
          if (o instanceof StringValue[]) {
              StringValue[] stringValues = (StringValue[])o;
              String[] strings = new String[stringValues.length];
              for (int i = 0; i < strings.length; i++)
                  strings[i] = stringValues[i].toString();
              return strings;
          }
          if (o instanceof int[]) {
              int[] ints = (int[])o;
              String[] strings = new String[ints.length];
              for (int i = 0; i < strings.length; i++)
                  strings[i] = Integer.toString(ints[i]);
              return strings;
          }
          if (o instanceof byte[]) {
              byte[] bytes = (byte[])o;
              String[] strings = new String[bytes.length];
              for (int i = 0; i < strings.length; i++)
                  strings[i] = Byte.toString(bytes[i]);
              return strings;
          }
          if (o instanceof Rational[]) {
              Rational[] rationals = (Rational[])o;
              String[] strings = new String[rationals.length];
              for (int i = 0; i < strings.length; i++)
                  strings[i] = rationals[i].toSimpleString(false);
              return strings;
          }
          return null;
      }
  
      /**
       * Gets the specified tag's value as a StringValue array, if possible.
       * Only succeeds if the tag is set as StringValue[], or StringValue.
       *
       * @param tagType the tag identifier
       * @return the tag's value as an array of StringValues. If the value is unset or cannot be converted, <code>null</code> is returned.
       */
      @Nullable
      public StringValue[] getStringValueArray(int tagType)
      {
          Object o = getObject(tagType);
          if (o == null)
              return null;
          if (o instanceof StringValue[])
              return (StringValue[])o;
          if (o instanceof StringValue)
              return new StringValue[] {(StringValue) o};
          return null;
      }
  
      /**
       * Gets the specified tag's value as an int array, if possible.  Only supported
       * where the tag is set as String, Integer, int[], byte[] or Rational[].
       *
       * @param tagType the tag identifier
       * @return the tag's value as an int array
       */
      @Nullable
      public int[] getIntArray(int tagType)
      {
          Object o = getObject(tagType);
          if (o == null)
              return null;
          if (o instanceof int[])
              return (int[])o;
          if (o instanceof Rational[]) {
              Rational[] rationals = (Rational[])o;
              int[] ints = new int[rationals.length];
              for (int i = 0; i < ints.length; i++) {
                  ints[i] = rationals[i].intValue();
              }
              return ints;
          }
          if (o instanceof short[]) {
              short[] shorts = (short[])o;
              int[] ints = new int[shorts.length];
              for (int i = 0; i < shorts.length; i++) {
                  ints[i] = shorts[i];
              }
              return ints;
          }
          if (o instanceof byte[]) {
              byte[] bytes = (byte[])o;
              int[] ints = new int[bytes.length];
              for (int i = 0; i < bytes.length; i++) {
                  ints[i] = bytes[i];
              }
              return ints;
          }
          if (o instanceof CharSequence) {
              CharSequence str = (CharSequence)o;
              int[] ints = new int[str.length()];
              for (int i = 0; i < str.length(); i++) {
                  ints[i] = str.charAt(i);
              }
              return ints;
          }
          if (o instanceof Integer)
              return new int[] { (Integer)o };
  
          return null;
      }
  
      /**
       * Gets the specified tag's value as an byte array, if possible.  Only supported
       * where the tag is set as String, Integer, int[], byte[] or Rational[].
       *
       * @param tagType the tag identifier
       * @return the tag's value as a byte array
       */
      @Nullable
      public byte[] getByteArray(int tagType)
      {
          Object o = getObject(tagType);
          if (o == null) {
              return null;
          } else if (o instanceof StringValue) {
              return ((StringValue)o).getBytes();
          } else if (o instanceof Rational[]) {
              Rational[] rationals = (Rational[])o;
              byte[] bytes = new byte[rationals.length];
              for (int i = 0; i < bytes.length; i++) {
                  bytes[i] = rationals[i].byteValue();
              }
              return bytes;
          } else if (o instanceof byte[]) {
              return (byte[])o;
          } else if (o instanceof int[]) {
              int[] ints = (int[])o;
              byte[] bytes = new byte[ints.length];
              for (int i = 0; i < ints.length; i++) {
                  bytes[i] = (byte)ints[i];
              }
              return bytes;
          } else if (o instanceof short[]) {
              short[] shorts = (short[])o;
              byte[] bytes = new byte[shorts.length];
              for (int i = 0; i < shorts.length; i++) {
                  bytes[i] = (byte)shorts[i];
              }
              return bytes;
          } else if (o instanceof CharSequence) {
              CharSequence str = (CharSequence)o;
              byte[] bytes = new byte[str.length()];
              for (int i = 0; i < str.length(); i++) {
                  bytes[i] = (byte)str.charAt(i);
              }
              return bytes;
          }
          if (o instanceof Integer)
              return new byte[] { ((Integer)o).byteValue() };
  
          return null;
      }
  
      /** Returns the specified tag's value as a double, if possible. */
      public double getDouble(int tagType) throws MetadataException
      {
          Double value = getDoubleObject(tagType);
          if (value!=null)
              return value;
          Object o = getObject(tagType);
          if (o == null)
              throw new MetadataException("Tag '" + getTagName(tagType) + "' has not been set -- check using containsTag() first");
          throw new MetadataException("Tag '" + tagType + "' cannot be converted to a double.  It is of type '" + o.getClass() + "'.");
      }
      /** Returns the specified tag's value as a Double.  If the tag is not set or cannot be converted, <code>null</code> is returned. */
      @Nullable
      public Double getDoubleObject(int tagType)
      {
          Object o = getObject(tagType);
          if (o == null)
              return null;
          if (o instanceof String || o instanceof StringValue) {
              try {
                  return Double.parseDouble(o.toString());
              } catch (NumberFormatException nfe) {
                  return null;
              }
          }
          if (o instanceof Number)
              return ((Number)o).doubleValue();
  
          return null;
      }
  
      /** Returns the specified tag's value as a float, if possible. */
      public float getFloat(int tagType) throws MetadataException
      {
          Float value = getFloatObject(tagType);
          if (value!=null)
              return value;
          Object o = getObject(tagType);
          if (o == null)
              throw new MetadataException("Tag '" + getTagName(tagType) + "' has not been set -- check using containsTag() first");
          throw new MetadataException("Tag '" + tagType + "' cannot be converted to a float.  It is of type '" + o.getClass() + "'.");
      }
  
      /** Returns the specified tag's value as a float.  If the tag is not set or cannot be converted, <code>null</code> is returned. */
      @Nullable
      public Float getFloatObject(int tagType)
      {
          Object o = getObject(tagType);
          if (o == null)
              return null;
          if (o instanceof String || o instanceof StringValue) {
              try {
                  return Float.parseFloat(o.toString());
              } catch (NumberFormatException nfe) {
                  return null;
              }
          }
          if (o instanceof Number)
              return ((Number)o).floatValue();
          return null;
      }
  
      /** Returns the specified tag's value as a long, if possible. */
      public long getLong(int tagType) throws MetadataException
      {
          Long value = getLongObject(tagType);
          if (value != null)
              return value;
          Object o = getObject(tagType);
          if (o == null)
              throw new MetadataException("Tag '" + getTagName(tagType) + "' has not been set -- check using containsTag() first");
          throw new MetadataException("Tag '" + tagType + "' cannot be converted to a long.  It is of type '" + o.getClass() + "'.");
      }
  
      /** Returns the specified tag's value as a long.  If the tag is not set or cannot be converted, <code>null</code> is returned. */
      @Nullable
      public Long getLongObject(int tagType)
      {
          Object o = getObject(tagType);
          if (o == null)
              return null;
          if (o instanceof Number)
              return ((Number)o).longValue();
          if (o instanceof String || o instanceof StringValue) {
              try {
                  return Long.parseLong(o.toString());
              } catch (NumberFormatException nfe) {
                  return null;
              }
          } else if (o instanceof Rational[]) {
              Rational[] rationals = (Rational[])o;
              if (rationals.length == 1)
                  return rationals[0].longValue();
          } else if (o instanceof byte[]) {
              byte[] bytes = (byte[])o;
              if (bytes.length == 1)
                  return (long)bytes[0];
          } else if (o instanceof int[]) {
              int[] ints = (int[])o;
              if (ints.length == 1)
                  return (long)ints[0];
          } else if (o instanceof short[]) {
              short[] shorts = (short[])o;
              if (shorts.length == 1)
                  return (long)shorts[0];
          }
          return null;
      }
  
      /** Returns the specified tag's value as a boolean, if possible. */
      public boolean getBoolean(int tagType) throws MetadataException
      {
          Boolean value = getBooleanObject(tagType);
          if (value != null)
              return value;
          Object o = getObject(tagType);
          if (o == null)
              throw new MetadataException("Tag '" + getTagName(tagType) + "' has not been set -- check using containsTag() first");
          throw new MetadataException("Tag '" + tagType + "' cannot be converted to a boolean.  It is of type '" + o.getClass() + "'.");
      }
  
      /** Returns the specified tag's value as a boolean.  If the tag is not set or cannot be converted, <code>null</code> is returned. */
      @Nullable
      @SuppressWarnings(value = "NP_BOOLEAN_RETURN_NULL", justification = "keep API interface consistent")
      public Boolean getBooleanObject(int tagType)
      {
          Object o = getObject(tagType);
          if (o == null)
              return null;
          if (o instanceof Boolean)
              return (Boolean)o;
          if (o instanceof String || o instanceof StringValue) {
              try {
                  return Boolean.getBoolean(o.toString());
              } catch (NumberFormatException nfe) {
                  return null;
              }
          }
          if (o instanceof Number)
              return (((Number)o).doubleValue() != 0);
          return null;
      }
  
      /**
       * Returns the specified tag's value as a java.util.Date.  If the value is unset or cannot be converted, <code>null</code> is returned.
       * <p>
       * If the underlying value is a {@link String}, then attempts will be made to parse the string as though it is in
       * the GMT {@link TimeZone}.  If the {@link TimeZone} is known, call the overload that accepts one as an argument.
       */
      @Nullable
      public java.util.Date getDate(int tagType)
      {
          return getDate(tagType, null, null);
      }
  
      /**
       * Returns the specified tag's value as a java.util.Date.  If the value is unset or cannot be converted, <code>null</code> is returned.
       * <p>
       * If the underlying value is a {@link String}, then attempts will be made to parse the string as though it is in
       * the {@link TimeZone} represented by the {@code timeZone} parameter (if it is non-null).  Note that this parameter
       * is only considered if the underlying value is a string and it has no time zone information, otherwise it has no effect.
       */
      @Nullable
      public java.util.Date getDate(int tagType, @Nullable TimeZone timeZone)
      {
          return getDate(tagType, null, timeZone);
      }
  
      /**
       * Returns the specified tag's value as a java.util.Date.  If the value is unset or cannot be converted, <code>null</code> is returned.
       * <p>
       * If the underlying value is a {@link String}, then attempts will be made to parse the string as though it is in
       * the {@link TimeZone} represented by the {@code timeZone} parameter (if it is non-null).  Note that this parameter
       * is only considered if the underlying value is a string and it has no time zone information, otherwise it has no effect.
       * In addition, the {@code subsecond} parameter, which specifies the number of digits after the decimal point in the seconds,
       * is set to the returned Date. This parameter is only considered if the underlying value is a string and is has
       * no subsecond information, otherwise it has no effect.
       *
       * @param tagType the tag identifier
       * @param subsecond the subsecond value for the Date
       * @param timeZone the time zone to use
       * @return a Date representing the time value
       */
      @Nullable
      public java.util.Date getDate(int tagType, @Nullable String subsecond, @Nullable TimeZone timeZone)
      {
          Object o = getObject(tagType);
  
          if (o instanceof java.util.Date)
              return (java.util.Date)o;
  
          java.util.Date date = null;
  
          if ((o instanceof String) || (o instanceof StringValue)) {
              // This seems to cover all known Exif and Xmp date strings
              // Note that "    :  :     :  :  " is a valid date string according to the Exif spec (which means 'unknown date'): http://www.awaresystems.be/imaging/tiff/tifftags/privateifd/exif/datetimeoriginal.html
              String datePatterns[] = {
                      "yyyy:MM:dd HH:mm:ss",
                      "yyyy:MM:dd HH:mm",
                      "yyyy-MM-dd HH:mm:ss",
                      "yyyy-MM-dd HH:mm",
                      "yyyy.MM.dd HH:mm:ss",
                      "yyyy.MM.dd HH:mm",
                      "yyyy-MM-dd'T'HH:mm:ss",
                      "yyyy-MM-dd'T'HH:mm",
                      "yyyy-MM-dd",
                      "yyyy-MM",
                      "yyyyMMdd", // as used in IPTC data
                      "yyyy" };
  
              String dateString = o.toString();
  
              // if the date string has subsecond information, it supersedes the subsecond parameter
              Pattern subsecondPattern = Pattern.compile("(\\d\\d:\\d\\d:\\d\\d)(\\.\\d+)");
              Matcher subsecondMatcher = subsecondPattern.matcher(dateString);
              if (subsecondMatcher.find()) {
                  subsecond = subsecondMatcher.group(2).substring(1);
                  dateString = subsecondMatcher.replaceAll("$1");
              }
  
              // if the date string has time zone information, it supersedes the timeZone parameter
              Pattern timeZonePattern = Pattern.compile("(Z|[+-]\\d\\d:\\d\\d)$");
              Matcher timeZoneMatcher = timeZonePattern.matcher(dateString);
              if (timeZoneMatcher.find()) {
                  timeZone = TimeZone.getTimeZone("GMT" + timeZoneMatcher.group().replaceAll("Z", ""));
                  dateString = timeZoneMatcher.replaceAll("");
              }
  
              for (String datePattern : datePatterns) {
                  try {
                      DateFormat parser = new SimpleDateFormat(datePattern);
                      if (timeZone != null)
                          parser.setTimeZone(timeZone);
                      else
                          parser.setTimeZone(TimeZone.getTimeZone("GMT")); // don't interpret zone time
  
                      date = parser.parse(dateString);
                      break;
                  } catch (ParseException ex) {
                      // simply try the next pattern
                  }
              }
          }
  
          if (date == null)
              return null;
  
          if (subsecond == null)
              return date;
  
          try {
              int millisecond = (int) (Double.parseDouble("." + subsecond) * 1000);
              if (millisecond >= 0 && millisecond < 1000) {
                  Calendar calendar = Calendar.getInstance();
                  calendar.setTime(date);
                  calendar.set(Calendar.MILLISECOND, millisecond);
                  return calendar.getTime();
              }
              return date;
          } catch (NumberFormatException e) {
              return date;
          }
      }
  
      /** Returns the specified tag's value as a Rational.  If the value is unset or cannot be converted, <code>null</code> is returned. */
      @Nullable
      public Rational getRational(int tagType)
      {
          Object o = getObject(tagType);
  
          if (o == null)
              return null;
  
          if (o instanceof Rational)
              return (Rational)o;
          if (o instanceof Integer)
              return new Rational((Integer)o, 1);
          if (o instanceof Long)
              return new Rational((Long)o, 1);
  
          // NOTE not doing conversions for real number types
  
          return null;
      }
  
      /** Returns the specified tag's value as an array of Rational.  If the value is unset or cannot be converted, <code>null</code> is returned. */
      @Nullable
      public Rational[] getRationalArray(int tagType)
      {
          Object o = getObject(tagType);
          if (o == null)
              return null;
  
          if (o instanceof Rational[])
              return (Rational[])o;
  
          return null;
      }
  
      /**
       * Returns the specified tag's value as a String.  This value is the 'raw' value.  A more presentable decoding
       * of this value may be obtained from the corresponding Descriptor.
       *
       * @return the String representation of the tag's value, or
       *         <code>null</code> if the tag hasn't been defined.
       */
      @Nullable
      public String getString(int tagType)
      {
          Object o = getObject(tagType);
          if (o == null)
              return null;
  
          if (o instanceof Rational)
              return ((Rational)o).toSimpleString(true);
  
          if (o.getClass().isArray()) {
              // handle arrays of objects and primitives
              int arrayLength = Array.getLength(o);
              final Class<?> componentType = o.getClass().getComponentType();
  
              StringBuilder string = new StringBuilder();
  
              if (Object.class.isAssignableFrom(componentType)) {
                  // object array
                  for (int i = 0; i < arrayLength; i++) {
                      if (i != 0)
                          string.append(' ');
                      string.append(Array.get(o, i).toString());
                  }
              } else if (componentType.getName().equals("int")) {
                  for (int i = 0; i < arrayLength; i++) {
                      if (i != 0)
                          string.append(' ');
                      string.append(Array.getInt(o, i));
                  }
              } else if (componentType.getName().equals("short")) {
                  for (int i = 0; i < arrayLength; i++) {
                      if (i != 0)
                          string.append(' ');
                      string.append(Array.getShort(o, i));
                  }
              } else if (componentType.getName().equals("long")) {
                  for (int i = 0; i < arrayLength; i++) {
                      if (i != 0)
                          string.append(' ');
                      string.append(Array.getLong(o, i));
                  }
              } else if (componentType.getName().equals("float")) {
                  DecimalFormat format = new DecimalFormat(_floatFormatPattern);
                  for (int i = 0; i < arrayLength; i++) {
                      if (i != 0)
                          string.append(' ');
                      String s = format.format(Array.getFloat(o, i));
                      string.append(s.equals("-0") ? "0" : s);
                  }
              } else if (componentType.getName().equals("double")) {
                  DecimalFormat format = new DecimalFormat(_floatFormatPattern);
                  for (int i = 0; i < arrayLength; i++) {
                      if (i != 0)
                          string.append(' ');
                      String s = format.format(Array.getDouble(o, i));
                      string.append(s.equals("-0") ? "0" : s);
                  }
              } else if (componentType.getName().equals("byte")) {
                  for (int i = 0; i < arrayLength; i++) {
                      if (i != 0)
                          string.append(' ');
                      string.append(Array.getByte(o, i) & 0xff);
                  }
              } else {
                  addError("Unexpected array component type: " + componentType.getName());
              }
  
              return string.toString();
          }
  
          if (o instanceof Double)
              return new DecimalFormat(_floatFormatPattern).format(((Double)o).doubleValue());
  
          if (o instanceof Float)
              return new DecimalFormat(_floatFormatPattern).format(((Float)o).floatValue());
  
          // Note that several cameras leave trailing spaces (Olympus, Nikon) but this library is intended to show
          // the actual data within the file.  It is not inconceivable that whitespace may be significant here, so we
          // do not trim.  Also, if support is added for writing data back to files, this may cause issues.
          // We leave trimming to the presentation layer.
          return o.toString();
      }
  
      @Nullable
      public String getString(int tagType, String charset)
      {
          byte[] bytes = getByteArray(tagType);
          if (bytes==null)
              return null;
          try {
              return new String(bytes, charset);
          } catch (UnsupportedEncodingException e) {
              return null;
          }
      }
  
      @Nullable
      public StringValue getStringValue(int tagType)
      {
          Object o = getObject(tagType);
          if (o instanceof StringValue)
              return (StringValue)o;
          return null;
      }
  
      /**
       * Returns the object hashed for the particular tag type specified, if available.
       *
       * @param tagType the tag type identifier
       * @return the tag's value as an Object if available, else <code>null</code>
       */
      @java.lang.SuppressWarnings({ "UnnecessaryBoxing" })
      @Nullable
      public Object getObject(int tagType)
      {
          return _tagMap.get(Integer.valueOf(tagType));
      }
  
  // OTHER METHODS
  
      /**
       * Returns the name of a specified tag as a String.
       *
       * @param tagType the tag type identifier
       * @return the tag's name as a String
       */
      @NotNull
      public String getTagName(int tagType)
      {
          HashMap<Integer, String> nameMap = getTagNameMap();
          if (!nameMap.containsKey(tagType)) {
              String hex = Integer.toHexString(tagType);
              while (hex.length() < 4) {
                  hex = "0" + hex;
              }
              return "Unknown tag (0x" + hex + ")";
          }
          return nameMap.get(tagType);
      }
  
      /**
       * Gets whether the specified tag is known by the directory and has a name.
       *
       * @param tagType the tag type identifier
       * @return whether this directory has a name for the specified tag
       */
      public boolean hasTagName(int tagType)
      {
          return getTagNameMap().containsKey(tagType);
      }
  
      /**
       * Provides a description of a tag's value using the descriptor set by
       * <code>setDescriptor(Descriptor)</code>.
       *
       * @param tagType the tag type identifier
       * @return the tag value's description as a String
       */
      @Nullable
      public String getDescription(int tagType)
      {
          assert(_descriptor != null);
          return _descriptor.getDescription(tagType);
      }
  
      @Override
      public String toString()
      {
          return String.format("%s Directory (%d %s)",
              getName(),
              _tagMap.size(),
              _tagMap.size() == 1
                  ? "tag"
                  : "tags");
      }
  }