Source for javax.imageio.metadata.IIOMetadata

   1: /* IIOMetadata.java --
   2:    Copyright (C) 2004  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package javax.imageio.metadata;
  40: 
  41: import org.w3c.dom.Node;
  42: 
  43: /**
  44:  * Represents metadata that describe an image or an image stream.
  45:  * Each ImageIO plugin will represent image data using an opaque
  46:  * object but all such objects should expose their internal
  47:  * information as a tree of IIOMetadataNodes.
  48:  *
  49:  * There are three formats of metadata that a plugin can support:
  50:  *
  51:  * <ul>
  52:  *   <li>a "native" format</li>
  53:  *   <li>a custom format</li>
  54:  *   <li>a standard plugin-neutral format</li>
  55:  * </ul>
  56:  *
  57:  * If a plugin supports more than one format of metadata, the other
  58:  * formats can be retrieved by calling getMetadataFormatNames.
  59:  *
  60:  * The native format is used to transfer metadata from one image to
  61:  * another image of the same type, losslessly.
  62:  *
  63:  * The custom format describes the image metadata and exposes a tree
  64:  * of IIOMetadataNodes but its internal representation is specific to
  65:  * this plugin.
  66:  *
  67:  * The plugin-neutral format uses a generic tree structure as its
  68:  * internal representation.
  69:  *
  70:  * ImageTranscoders may be used to convert metadata understood by one
  71:  * plugin to metadata understood by another, however the conversion
  72:  * may be lossy.
  73:  *
  74:  * @author Michael Koch (konqueror@gmx.de)
  75:  * @author Thomas Fitzsimmons (fitzsim@redhat.com)
  76:  */
  77: public abstract class IIOMetadata
  78: {
  79:   protected IIOMetadataController controller;
  80:   protected IIOMetadataController defaultController;
  81:   protected String[] extraMetadataFormatClassNames;
  82:   protected String[] extraMetadataFormatNames;
  83:   protected String nativeMetadataFormatClassName;
  84:   protected String nativeMetadataFormatName;
  85:   protected boolean standardFormatSupported;
  86: 
  87:   /**
  88:    * Construct an IIOMetadata object.
  89:    */
  90:   protected IIOMetadata()
  91:   {
  92:     // Do nothing here.
  93:   }
  94: 
  95:   /**
  96:    * Construct an IIOMetadata object.
  97:    *
  98:    * @param standardMetadataFormatSupported
  99:    * @param nativeMetadataFormatName
 100:    * @param nativeMetadataFormatClassName
 101:    * @param extraMetadataFormatNames
 102:    * @param extraMetadataFormatClassNames
 103:    *
 104:    * @throws IllegalArgumentException if extraMetadataFormatNames has length of
 105:    * zero or extraMetadataFormatNames and extraMetadataFormatClassNames are
 106:    * neither both null, not have the same length
 107:    */
 108:   protected IIOMetadata(boolean standardMetadataFormatSupported,
 109:                         String nativeMetadataFormatName,
 110:                         String nativeMetadataFormatClassName,
 111:                         String[] extraMetadataFormatNames,
 112:                         String[] extraMetadataFormatClassNames)
 113:   {
 114:     if (extraMetadataFormatNames != null
 115:         && extraMetadataFormatNames.length == 0)
 116:       throw new IllegalArgumentException
 117:         ("extraMetadataFormatNames may not be empty");
 118: 
 119:     if (((extraMetadataFormatNames == null)
 120:          && (extraMetadataFormatClassNames != null))
 121:         || ((extraMetadataFormatNames != null)
 122:             && (extraMetadataFormatClassNames == null))
 123:         || ((extraMetadataFormatNames != null)
 124:             && (extraMetadataFormatClassNames != null)
 125:             && (extraMetadataFormatNames.length !=
 126:                 extraMetadataFormatClassNames.length)))
 127:       throw new IllegalArgumentException
 128:         ("extraMetadataFormatNames and extraMetadataFormatClassNames " +
 129:          "have different lengths");
 130: 
 131:     this.standardFormatSupported = standardMetadataFormatSupported;
 132:     this.nativeMetadataFormatName = nativeMetadataFormatName;
 133:     this.nativeMetadataFormatClassName = nativeMetadataFormatClassName;
 134:     this.extraMetadataFormatNames = extraMetadataFormatNames;
 135:     this.extraMetadataFormatClassNames = extraMetadataFormatClassNames;
 136:   }
 137: 
 138:   public boolean activateController()
 139:   {
 140:     if (! hasController())
 141:       return false;
 142: 
 143:     return getDefaultController().activate(this);
 144:   }
 145: 
 146:   public IIOMetadataController getController()
 147:   {
 148:     return controller;
 149:   }
 150: 
 151:   public IIOMetadataController getDefaultController()
 152:   {
 153:     return defaultController;
 154:   }
 155: 
 156:   public String[] getExtraMetadataFormatNames()
 157:   {
 158:     return (String[]) extraMetadataFormatNames.clone();
 159:   }
 160: 
 161:   public IIOMetadataFormat getMetadataFormat(String formatName)
 162:   {
 163:     if (formatName == null)
 164:       throw new IllegalArgumentException("formatName may not be null");
 165:     
 166:     String formatClassName = null;
 167: 
 168:     if (isStandardMetadataFormatSupported()
 169:     && formatName.equals(nativeMetadataFormatName))
 170:       formatClassName = nativeMetadataFormatClassName;
 171:     else
 172:       {
 173:     String[] extraFormatNames = getExtraMetadataFormatNames();
 174:     
 175:     for (int i = extraFormatNames.length - 1; i >= 0; --i)
 176:       if (extraFormatNames[i].equals(formatName))
 177:         {
 178:           formatClassName = extraFormatNames[i];
 179:           break;
 180:         }
 181:       }
 182: 
 183:     if (formatClassName == null)
 184:       throw new IllegalArgumentException("unknown format");
 185: 
 186:     IIOMetadataFormat format;
 187:     
 188:     try
 189:       {
 190:     format = (IIOMetadataFormat) Class.forName(formatClassName)
 191:                       .newInstance();
 192:       }
 193:     catch (Exception e)
 194:       {
 195:     IllegalStateException ise = new IllegalStateException();
 196:     ise.initCause(e);
 197:     throw ise;
 198:       }
 199: 
 200:     return format;
 201:   }
 202: 
 203:   public String[] getMetadataFormatNames()
 204:   {
 205:     String[] formatNames = getExtraMetadataFormatNames();
 206:     
 207:     if (isStandardMetadataFormatSupported())
 208:       {
 209:         // Combine native metadata format name and extra metadata format names
 210:     // into one String array.
 211:     String[] tmp = new String[formatNames.length + 1];
 212:     tmp[0] = getNativeMetadataFormatName();
 213: 
 214:     for (int i = 1; i < tmp.length; ++i)
 215:       tmp[i] = formatNames[i - 1];
 216: 
 217:     formatNames = tmp;
 218:       }
 219: 
 220:     return formatNames;
 221:   }
 222: 
 223:   public String getNativeMetadataFormatName()
 224:   {
 225:     return nativeMetadataFormatName;
 226:   }
 227: 
 228:   public boolean hasController()
 229:   {
 230:     return getController() != null;
 231:   }
 232: 
 233:   public abstract boolean isReadOnly();
 234: 
 235:   public boolean isStandardMetadataFormatSupported()
 236:   {
 237:     return standardFormatSupported;
 238:   }
 239: 
 240:   public abstract void reset();
 241: 
 242:   public void setController(IIOMetadataController controller)
 243:   {
 244:     this.controller = controller;
 245:   }
 246: 
 247:   public abstract Node getAsTree (String formatName);
 248: 
 249:   protected IIOMetadataNode getStandardChromaNode ()
 250:   {
 251:     return null;
 252:   }
 253: 
 254:   protected IIOMetadataNode getStandardCompressionNode ()
 255:   {
 256:     return null;
 257:   }
 258: 
 259:   protected IIOMetadataNode getStandardDataNode ()
 260:   {
 261:     return null;
 262:   }
 263: 
 264:   protected IIOMetadataNode getStandardDimensionNode ()
 265:   {
 266:     return null;
 267:   }
 268: 
 269:   protected IIOMetadataNode getStandardDocumentNode ()
 270:   {
 271:     return null;
 272:   }
 273: 
 274:   protected IIOMetadataNode getStandardTextNode ()
 275:   {
 276:     return null;
 277:   }
 278: 
 279:   protected IIOMetadataNode getStandardTileNode ()
 280:   {
 281:     return null;
 282:   }
 283: 
 284:   protected IIOMetadataNode getStandardTransparencyNode ()
 285:   {
 286:     return null;
 287:   }
 288: 
 289:   private void appendChild (IIOMetadataNode node,
 290:                 IIOMetadataNode child)
 291:   {
 292:     if (child != null)
 293:       node.appendChild(child);
 294:   }
 295: 
 296:   protected final IIOMetadataNode getStandardTree ()
 297:   {
 298:     IIOMetadataNode node = new IIOMetadataNode();
 299: 
 300:     appendChild (node, getStandardChromaNode());
 301:     appendChild (node, getStandardCompressionNode());
 302:     appendChild (node, getStandardDataNode());
 303:     appendChild (node, getStandardDimensionNode());
 304:     appendChild (node, getStandardDocumentNode());
 305:     appendChild (node, getStandardTextNode());
 306:     appendChild (node, getStandardTileNode());
 307:     appendChild (node, getStandardTransparencyNode());
 308: 
 309:     return node;
 310:   }
 311: 
 312:   public abstract void mergeTree (String formatName,
 313:                                   Node root)
 314:     throws IIOInvalidTreeException;
 315: 
 316:   public void setFromTree (String formatName, Node root)
 317:     throws IIOInvalidTreeException
 318:   {
 319:     reset();
 320: 
 321:     mergeTree (formatName, root);
 322:   }
 323: }