src/share/classes/javax/imageio/spi/ImageReaderWriterSpi.java

Print this page


   1 /*
   2  * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any


 222                                 String nativeStreamMetadataFormatName,
 223                                 String nativeStreamMetadataFormatClassName,
 224                                 String[] extraStreamMetadataFormatNames,
 225                                 String[] extraStreamMetadataFormatClassNames,
 226                                 boolean supportsStandardImageMetadataFormat,
 227                                 String nativeImageMetadataFormatName,
 228                                 String nativeImageMetadataFormatClassName,
 229                                 String[] extraImageMetadataFormatNames,
 230                                 String[] extraImageMetadataFormatClassNames) {
 231         super(vendorName, version);
 232         if (names == null) {
 233             throw new IllegalArgumentException("names == null!");
 234         }
 235         if (names.length == 0) {
 236             throw new IllegalArgumentException("names.length == 0!");
 237         }
 238         if (pluginClassName == null) {
 239             throw new IllegalArgumentException("pluginClassName == null!");
 240         }
 241 
 242         this.names = (String[])names.clone();
 243         // If length == 0, leave it null
 244         if (suffixes != null && suffixes.length > 0) {
 245             this.suffixes = (String[])suffixes.clone();
 246         }
 247         // If length == 0, leave it null
 248         if (MIMETypes != null && MIMETypes.length > 0) {
 249             this.MIMETypes = (String[])MIMETypes.clone();
 250         }
 251         this.pluginClassName = pluginClassName;
 252 
 253         this.supportsStandardStreamMetadataFormat =
 254             supportsStandardStreamMetadataFormat;
 255         this.nativeStreamMetadataFormatName = nativeStreamMetadataFormatName;
 256         this.nativeStreamMetadataFormatClassName =
 257             nativeStreamMetadataFormatClassName;
 258         // If length == 0, leave it null
 259         if (extraStreamMetadataFormatNames != null &&
 260             extraStreamMetadataFormatNames.length > 0) {
 261             this.extraStreamMetadataFormatNames =
 262                 (String[])extraStreamMetadataFormatNames.clone();
 263         }
 264         // If length == 0, leave it null
 265         if (extraStreamMetadataFormatClassNames != null &&
 266             extraStreamMetadataFormatClassNames.length > 0) {
 267             this.extraStreamMetadataFormatClassNames =
 268                 (String[])extraStreamMetadataFormatClassNames.clone();
 269         }
 270         this.supportsStandardImageMetadataFormat =
 271             supportsStandardImageMetadataFormat;
 272         this.nativeImageMetadataFormatName = nativeImageMetadataFormatName;
 273         this.nativeImageMetadataFormatClassName =
 274             nativeImageMetadataFormatClassName;
 275         // If length == 0, leave it null
 276         if (extraImageMetadataFormatNames != null &&
 277             extraImageMetadataFormatNames.length > 0) {
 278             this.extraImageMetadataFormatNames =
 279                 (String[])extraImageMetadataFormatNames.clone();
 280         }
 281         // If length == 0, leave it null
 282         if (extraImageMetadataFormatClassNames != null &&
 283             extraImageMetadataFormatClassNames.length > 0) {
 284             this.extraImageMetadataFormatClassNames =
 285                 (String[])extraImageMetadataFormatClassNames.clone();
 286         }
 287     }
 288 
 289     /**
 290      * Constructs a blank <code>ImageReaderWriterSpi</code>.  It is up
 291      * to the subclass to initialize instance variables and/or
 292      * override method implementations in order to provide working
 293      * versions of all methods.
 294      */
 295     public ImageReaderWriterSpi() {
 296     }
 297 
 298     /**
 299      * Returns an array of <code>String</code>s containing
 300      * human-readable names for the formats that are generally usable
 301      * by the <code>ImageReader</code> or <code>ImageWriter</code>
 302      * implementation associated with this service provider.  For
 303      * example, a single <code>ImageReader</code> might be able to
 304      * process both PBM and PNM files.
 305      *
 306      * @return a non-<code>null</code> array of <code>String</code>s
 307      * or length at least 1 containing informal format names
 308      * associated with this reader or writer.
 309      */
 310     public String[] getFormatNames() {
 311         return (String[])names.clone();
 312     }
 313 
 314     /**
 315      * Returns an array of <code>String</code>s containing a list of
 316      * file suffixes associated with the formats that are generally
 317      * usable by the <code>ImageReader</code> or
 318      * <code>ImageWriter</code> implementation associated with this
 319      * service provider.  For example, a single
 320      * <code>ImageReader</code> might be able to process files with
 321      * '.pbm' and '.pnm' suffixes, or both '.jpg' and '.jpeg'
 322      * suffixes.  If there are no known file suffixes,
 323      * <code>null</code> will be returned.
 324      *
 325      * <p> Returning a particular suffix does not guarantee that files
 326      * with that suffix can be processed; it merely indicates that it
 327      * may be worthwhile attempting to decode or encode such files
 328      * using this service provider.
 329      *
 330      * @return an array of <code>String</code>s or length at least 1
 331      * containing common file suffixes associated with this reader or
 332      * writer, or <code>null</code>.
 333      */
 334     public String[] getFileSuffixes() {
 335         return suffixes == null ? null : (String[])suffixes.clone();
 336     }
 337 
 338     /**
 339      * Returns an array of <code>String</code>s containing a list of
 340      * MIME types associated with the formats that are generally
 341      * usable by the <code>ImageReader</code> or
 342      * <code>ImageWriter</code> implementation associated with this
 343      * service provider.
 344      *
 345      * <p> Ideally, only a single MIME type would be required in order
 346      * to describe a particular format.  However, for several reasons
 347      * it is necessary to associate a list of types with each service
 348      * provider.  First, many common image file formats do not have
 349      * standard MIME types, so a list of commonly used unofficial
 350      * names will be required, such as <code>image/x-pbm</code> and
 351      * <code>image/x-portable-bitmap</code>.  Some file formats have
 352      * official MIME types but may sometimes be referred to using
 353      * their previous unofficial designations, such as
 354      * <code>image/x-png</code> instead of the official
 355      * <code>image/png</code>.  Finally, a single service provider may
 356      * be capable of parsing multiple distinct types from the MIME
 357      * point of view, for example <code>image/x-xbitmap</code> and
 358      * <code>image/x-xpixmap</code>.
 359      *
 360      * <p> Returning a particular MIME type does not guarantee that
 361      * files claiming to be of that type can be processed; it merely
 362      * indicates that it may be worthwhile attempting to decode or
 363      * encode such files using this service provider.
 364      *
 365      * @return an array of <code>String</code>s or length at least 1
 366      * containing MIME types associated with this reader or writer, or
 367      * <code>null</code>.
 368      */
 369     public String[] getMIMETypes() {
 370         return MIMETypes == null ? null : (String[])MIMETypes.clone();
 371     }
 372 
 373     /**
 374      * Returns the fully-qualified class name of the
 375      * <code>ImageReader</code> or <code>ImageWriter</code> plug-in
 376      * associated with this service provider.
 377      *
 378      * @return the class name, as a non-<code>null</code>
 379      * <code>String</code>.
 380      */
 381     public String getPluginClassName() {
 382         return pluginClassName;
 383     }
 384 
 385     /**
 386      * Returns <code>true</code> if the standard metadata format is
 387      * among the document formats recognized by the
 388      * <code>getAsTree</code> and <code>setFromTree</code> methods on
 389      * the stream metadata objects produced or consumed by this
 390      * plug-in.


 426      * <p> If the plug-in does not handle metadata, null should be
 427      * returned.
 428      *
 429      * <p> The set of formats may differ according to the particular
 430      * images being read or written; this method should indicate all
 431      * the additional formats supported by the plug-in under any
 432      * circumstances.
 433      *
 434      * <p> The default implementation returns a clone of the
 435      * <code>extraStreamMetadataFormatNames</code> instance variable,
 436      * which is typically set by the constructor.
 437      *
 438      * @return an array of <code>String</code>s, or null.
 439      *
 440      * @see IIOMetadata#getMetadataFormatNames
 441      * @see #getExtraImageMetadataFormatNames
 442      * @see #getNativeStreamMetadataFormatName
 443      */
 444     public String[] getExtraStreamMetadataFormatNames() {
 445         return extraStreamMetadataFormatNames == null ?
 446             null : (String[])extraStreamMetadataFormatNames.clone();
 447     }
 448 
 449     /**
 450      * Returns <code>true</code> if the standard metadata format is
 451      * among the document formats recognized by the
 452      * <code>getAsTree</code> and <code>setFromTree</code> methods on
 453      * the image metadata objects produced or consumed by this
 454      * plug-in.
 455      *
 456      * @return <code>true</code> if the standard format is supported
 457      * for image metadata.
 458      */
 459     public boolean isStandardImageMetadataFormatSupported() {
 460         return supportsStandardImageMetadataFormat;
 461     }
 462 
 463     /**
 464      * Returns the name of the "native" image metadata format for
 465      * this plug-in, which typically allows for lossless encoding and
 466      * transmission of the image metadata stored in the format handled by


 490      *
 491      * <p> If the plug-in does not handle image metadata, null should
 492      * be returned.
 493      *
 494      * <p> The set of formats may differ according to the particular
 495      * images being read or written; this method should indicate all
 496      * the additional formats supported by the plug-in under any circumstances.
 497      *
 498      * <p> The default implementation returns a clone of the
 499      * <code>extraImageMetadataFormatNames</code> instance variable,
 500      * which is typically set by the constructor.
 501      *
 502      * @return an array of <code>String</code>s, or null.
 503      *
 504      * @see IIOMetadata#getMetadataFormatNames
 505      * @see #getExtraStreamMetadataFormatNames
 506      * @see #getNativeImageMetadataFormatName
 507      */
 508     public String[] getExtraImageMetadataFormatNames() {
 509         return extraImageMetadataFormatNames == null ?
 510             null : (String[])extraImageMetadataFormatNames.clone();
 511     }
 512 
 513     /**
 514      * Returns an <code>IIOMetadataFormat</code> object describing the
 515      * given stream metadata format, or <code>null</code> if no
 516      * description is available.  The supplied name must be the native
 517      * stream metadata format name, the standard metadata format name,
 518      * or one of those returned by
 519      * <code>getExtraStreamMetadataFormatNames</code>.
 520      *
 521      * @param formatName the desired stream metadata format.
 522      *
 523      * @return an <code>IIOMetadataFormat</code> object.
 524      *
 525      * @exception IllegalArgumentException if <code>formatName</code>
 526      * is <code>null</code> or is not a supported name.
 527      */
 528     public IIOMetadataFormat getStreamMetadataFormat(String formatName) {
 529         return getMetadataFormat(formatName,
 530                                  supportsStandardStreamMetadataFormat,


   1 /*
   2  * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any


 222                                 String nativeStreamMetadataFormatName,
 223                                 String nativeStreamMetadataFormatClassName,
 224                                 String[] extraStreamMetadataFormatNames,
 225                                 String[] extraStreamMetadataFormatClassNames,
 226                                 boolean supportsStandardImageMetadataFormat,
 227                                 String nativeImageMetadataFormatName,
 228                                 String nativeImageMetadataFormatClassName,
 229                                 String[] extraImageMetadataFormatNames,
 230                                 String[] extraImageMetadataFormatClassNames) {
 231         super(vendorName, version);
 232         if (names == null) {
 233             throw new IllegalArgumentException("names == null!");
 234         }
 235         if (names.length == 0) {
 236             throw new IllegalArgumentException("names.length == 0!");
 237         }
 238         if (pluginClassName == null) {
 239             throw new IllegalArgumentException("pluginClassName == null!");
 240         }
 241 
 242         this.names = names.clone();
 243         // If length == 0, leave it null
 244         if (suffixes != null && suffixes.length > 0) {
 245             this.suffixes = suffixes.clone();
 246         }
 247         // If length == 0, leave it null
 248         if (MIMETypes != null && MIMETypes.length > 0) {
 249             this.MIMETypes = MIMETypes.clone();
 250         }
 251         this.pluginClassName = pluginClassName;
 252 
 253         this.supportsStandardStreamMetadataFormat =
 254             supportsStandardStreamMetadataFormat;
 255         this.nativeStreamMetadataFormatName = nativeStreamMetadataFormatName;
 256         this.nativeStreamMetadataFormatClassName =
 257             nativeStreamMetadataFormatClassName;
 258         // If length == 0, leave it null
 259         if (extraStreamMetadataFormatNames != null &&
 260             extraStreamMetadataFormatNames.length > 0) {
 261             this.extraStreamMetadataFormatNames =
 262                 extraStreamMetadataFormatNames.clone();
 263         }
 264         // If length == 0, leave it null
 265         if (extraStreamMetadataFormatClassNames != null &&
 266             extraStreamMetadataFormatClassNames.length > 0) {
 267             this.extraStreamMetadataFormatClassNames =
 268                 extraStreamMetadataFormatClassNames.clone();
 269         }
 270         this.supportsStandardImageMetadataFormat =
 271             supportsStandardImageMetadataFormat;
 272         this.nativeImageMetadataFormatName = nativeImageMetadataFormatName;
 273         this.nativeImageMetadataFormatClassName =
 274             nativeImageMetadataFormatClassName;
 275         // If length == 0, leave it null
 276         if (extraImageMetadataFormatNames != null &&
 277             extraImageMetadataFormatNames.length > 0) {
 278             this.extraImageMetadataFormatNames =
 279                 extraImageMetadataFormatNames.clone();
 280         }
 281         // If length == 0, leave it null
 282         if (extraImageMetadataFormatClassNames != null &&
 283             extraImageMetadataFormatClassNames.length > 0) {
 284             this.extraImageMetadataFormatClassNames =
 285                 extraImageMetadataFormatClassNames.clone();
 286         }
 287     }
 288 
 289     /**
 290      * Constructs a blank <code>ImageReaderWriterSpi</code>.  It is up
 291      * to the subclass to initialize instance variables and/or
 292      * override method implementations in order to provide working
 293      * versions of all methods.
 294      */
 295     public ImageReaderWriterSpi() {
 296     }
 297 
 298     /**
 299      * Returns an array of <code>String</code>s containing
 300      * human-readable names for the formats that are generally usable
 301      * by the <code>ImageReader</code> or <code>ImageWriter</code>
 302      * implementation associated with this service provider.  For
 303      * example, a single <code>ImageReader</code> might be able to
 304      * process both PBM and PNM files.
 305      *
 306      * @return a non-<code>null</code> array of <code>String</code>s
 307      * or length at least 1 containing informal format names
 308      * associated with this reader or writer.
 309      */
 310     public String[] getFormatNames() {
 311         return names.clone();
 312     }
 313 
 314     /**
 315      * Returns an array of <code>String</code>s containing a list of
 316      * file suffixes associated with the formats that are generally
 317      * usable by the <code>ImageReader</code> or
 318      * <code>ImageWriter</code> implementation associated with this
 319      * service provider.  For example, a single
 320      * <code>ImageReader</code> might be able to process files with
 321      * '.pbm' and '.pnm' suffixes, or both '.jpg' and '.jpeg'
 322      * suffixes.  If there are no known file suffixes,
 323      * <code>null</code> will be returned.
 324      *
 325      * <p> Returning a particular suffix does not guarantee that files
 326      * with that suffix can be processed; it merely indicates that it
 327      * may be worthwhile attempting to decode or encode such files
 328      * using this service provider.
 329      *
 330      * @return an array of <code>String</code>s or length at least 1
 331      * containing common file suffixes associated with this reader or
 332      * writer, or <code>null</code>.
 333      */
 334     public String[] getFileSuffixes() {
 335         return suffixes == null ? null : suffixes.clone();
 336     }
 337 
 338     /**
 339      * Returns an array of <code>String</code>s containing a list of
 340      * MIME types associated with the formats that are generally
 341      * usable by the <code>ImageReader</code> or
 342      * <code>ImageWriter</code> implementation associated with this
 343      * service provider.
 344      *
 345      * <p> Ideally, only a single MIME type would be required in order
 346      * to describe a particular format.  However, for several reasons
 347      * it is necessary to associate a list of types with each service
 348      * provider.  First, many common image file formats do not have
 349      * standard MIME types, so a list of commonly used unofficial
 350      * names will be required, such as <code>image/x-pbm</code> and
 351      * <code>image/x-portable-bitmap</code>.  Some file formats have
 352      * official MIME types but may sometimes be referred to using
 353      * their previous unofficial designations, such as
 354      * <code>image/x-png</code> instead of the official
 355      * <code>image/png</code>.  Finally, a single service provider may
 356      * be capable of parsing multiple distinct types from the MIME
 357      * point of view, for example <code>image/x-xbitmap</code> and
 358      * <code>image/x-xpixmap</code>.
 359      *
 360      * <p> Returning a particular MIME type does not guarantee that
 361      * files claiming to be of that type can be processed; it merely
 362      * indicates that it may be worthwhile attempting to decode or
 363      * encode such files using this service provider.
 364      *
 365      * @return an array of <code>String</code>s or length at least 1
 366      * containing MIME types associated with this reader or writer, or
 367      * <code>null</code>.
 368      */
 369     public String[] getMIMETypes() {
 370         return MIMETypes == null ? null : MIMETypes.clone();
 371     }
 372 
 373     /**
 374      * Returns the fully-qualified class name of the
 375      * <code>ImageReader</code> or <code>ImageWriter</code> plug-in
 376      * associated with this service provider.
 377      *
 378      * @return the class name, as a non-<code>null</code>
 379      * <code>String</code>.
 380      */
 381     public String getPluginClassName() {
 382         return pluginClassName;
 383     }
 384 
 385     /**
 386      * Returns <code>true</code> if the standard metadata format is
 387      * among the document formats recognized by the
 388      * <code>getAsTree</code> and <code>setFromTree</code> methods on
 389      * the stream metadata objects produced or consumed by this
 390      * plug-in.


 426      * <p> If the plug-in does not handle metadata, null should be
 427      * returned.
 428      *
 429      * <p> The set of formats may differ according to the particular
 430      * images being read or written; this method should indicate all
 431      * the additional formats supported by the plug-in under any
 432      * circumstances.
 433      *
 434      * <p> The default implementation returns a clone of the
 435      * <code>extraStreamMetadataFormatNames</code> instance variable,
 436      * which is typically set by the constructor.
 437      *
 438      * @return an array of <code>String</code>s, or null.
 439      *
 440      * @see IIOMetadata#getMetadataFormatNames
 441      * @see #getExtraImageMetadataFormatNames
 442      * @see #getNativeStreamMetadataFormatName
 443      */
 444     public String[] getExtraStreamMetadataFormatNames() {
 445         return extraStreamMetadataFormatNames == null ?
 446             null : extraStreamMetadataFormatNames.clone();
 447     }
 448 
 449     /**
 450      * Returns <code>true</code> if the standard metadata format is
 451      * among the document formats recognized by the
 452      * <code>getAsTree</code> and <code>setFromTree</code> methods on
 453      * the image metadata objects produced or consumed by this
 454      * plug-in.
 455      *
 456      * @return <code>true</code> if the standard format is supported
 457      * for image metadata.
 458      */
 459     public boolean isStandardImageMetadataFormatSupported() {
 460         return supportsStandardImageMetadataFormat;
 461     }
 462 
 463     /**
 464      * Returns the name of the "native" image metadata format for
 465      * this plug-in, which typically allows for lossless encoding and
 466      * transmission of the image metadata stored in the format handled by


 490      *
 491      * <p> If the plug-in does not handle image metadata, null should
 492      * be returned.
 493      *
 494      * <p> The set of formats may differ according to the particular
 495      * images being read or written; this method should indicate all
 496      * the additional formats supported by the plug-in under any circumstances.
 497      *
 498      * <p> The default implementation returns a clone of the
 499      * <code>extraImageMetadataFormatNames</code> instance variable,
 500      * which is typically set by the constructor.
 501      *
 502      * @return an array of <code>String</code>s, or null.
 503      *
 504      * @see IIOMetadata#getMetadataFormatNames
 505      * @see #getExtraStreamMetadataFormatNames
 506      * @see #getNativeImageMetadataFormatName
 507      */
 508     public String[] getExtraImageMetadataFormatNames() {
 509         return extraImageMetadataFormatNames == null ?
 510             null : extraImageMetadataFormatNames.clone();
 511     }
 512 
 513     /**
 514      * Returns an <code>IIOMetadataFormat</code> object describing the
 515      * given stream metadata format, or <code>null</code> if no
 516      * description is available.  The supplied name must be the native
 517      * stream metadata format name, the standard metadata format name,
 518      * or one of those returned by
 519      * <code>getExtraStreamMetadataFormatNames</code>.
 520      *
 521      * @param formatName the desired stream metadata format.
 522      *
 523      * @return an <code>IIOMetadataFormat</code> object.
 524      *
 525      * @exception IllegalArgumentException if <code>formatName</code>
 526      * is <code>null</code> or is not a supported name.
 527      */
 528     public IIOMetadataFormat getStreamMetadataFormat(String formatName) {
 529         return getMetadataFormat(formatName,
 530                                  supportsStandardStreamMetadataFormat,