libjava/java/net/ContentHandler.java

   1 /* ContentHandler.java -- Abstract class for handling content from URL's
   2    Copyright (C) 1998, 1999, 2000, 2001, 2003 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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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 package java.net;
  39
  40 import java.io.IOException;
  41
  42 /**
  43  * Written using on-line Java Platform 1.2 API Specification, as well
  44  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
  45  * Status:  Believed complete and correct.
  46  */
  47
  48 /**
  49   * This is an abstract class that is the superclass for classes that read
  50   * objects from URL's.  Calling the <code>getContent()</code> method in the
  51   * <code>URL</code> class or the <code>URLConnection</code> class will cause
  52   * an instance of a subclass of <code>ContentHandler</code> to be created for
  53   * the MIME type of the object being downloaded from the URL.  Thus, this
  54   * class is seldom needed by applications/applets directly, but only
  55   * indirectly through methods in other classes.
  56   *
  57   * @author Aaron M. Renn (arenn@urbanophile.com)
  58   * @author Warren Levy (warrenl@cygnus.com)
  59   */
  60 public abstract class ContentHandler
  61 {
  62   /*
  63    * Constructors
  64    */
  65
  66   /**
  67     * Default, no-argument constructor.
  68     */
  69   public ContentHandler()
  70   {
  71   }
  72
  73   /*
  74    * Instance Methods
  75    */
  76
  77   /**
  78     * This method reads from the <code>InputStream</code> of the passed in URL
  79     * connection and uses the data downloaded to create an <code>Object</code>
  80     * represening the content.  For example, if the URL is pointing to a GIF
  81     * file, this method might return an <code>Image</code> object.  This method
  82     * must be implemented by subclasses.
  83     *
  84     * @param urlc A <code>URLConnection</code> object to read data from.
  85     *
  86     * @return An object representing the data read
  87     *
  88     * @exception IOException If an error occurs
  89     */
  90   public abstract Object getContent(URLConnection urlc)
  91     throws IOException;
  92
  93   /**
  94     * This method reads from the <code>InputStream</code> of the passed in URL
  95     * connection and uses the data downloaded to create an <code>Object</code>
  96     * represening the content.  For example, if the URL is pointing to a GIF
  97     * file, this method might return an <code>Image</code> object.  This method
  98     * must be implemented by subclasses.  This method uses the list of
  99     * supplied classes as candidate types.  If the data read doesn't match
 100     * any of the supplied type, <code>null</code> is returned.
 101     *
 102     * @param urlc A <code>URLConnection</code> object to read data from.
 103     * @param classes An array of types of objects that are candidate types
 104     * for the data to be read.
 105     *
 106     * @return An object representing the data read, or <code>null</code>
 107     * if the data does not match any of the candidate types.
 108     *
 109     * @exception IOException If an error occurs
 110     *
 111     * @since 1.3
 112     */
 113   public Object getContent(URLConnection urlc, Class[] classes)
 114     throws IOException
 115   {
 116     Object obj = getContent(urlc);
 117
 118     for (int i = 0; i < classes.length; i++)
 119       {
 120         if (classes[i].isInstance(obj))
 121           return obj;
 122       }
 123
 124     return null;
 125   }
 126 } // class ContentHandler