View Javadoc
1   /*
2    * Copyright (c) 1995, 2013, 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
23   * questions.
24   */
25  
26  package java.net;
27  
28  import java.io.IOException;
29  
30  /**
31   * The abstract class {@code ContentHandler} is the superclass
32   * of all classes that read an {@code Object} from a
33   * {@code URLConnection}.
34   * <p>
35   * An application does not generally call the
36   * {@code getContent} method in this class directly. Instead, an
37   * application calls the {@code getContent} method in class
38   * {@code URL} or in {@code URLConnection}.
39   * The application's content handler factory (an instance of a class that
40   * implements the interface {@code ContentHandlerFactory} set
41   * up by a call to {@code setContentHandler}) is
42   * called with a {@code String} giving the MIME type of the
43   * object being received on the socket. The factory returns an
44   * instance of a subclass of {@code ContentHandler}, and its
45   * {@code getContent} method is called to create the object.
46   * <p>
47   * If no content handler could be found, URLConnection will
48   * look for a content handler in a user-defineable set of places.
49   * By default it looks in sun.net.www.content, but users can define a
50   * vertical-bar delimited set of class prefixes to search through in
51   * addition by defining the java.content.handler.pkgs property.
52   * The class name must be of the form:
53   * <pre>
54   *     {package-prefix}.{major}.{minor}
55   * e.g.
56   *     YoyoDyne.experimental.text.plain
57   * </pre>
58   * If the loading of the content handler class would be performed by
59   * a classloader that is outside of the delegation chain of the caller,
60   * the JVM will need the RuntimePermission "getClassLoader".
61   *
62   * @author  James Gosling
63   * @see     java.net.ContentHandler#getContent(java.net.URLConnection)
64   * @see     java.net.ContentHandlerFactory
65   * @see     java.net.URL#getContent()
66   * @see     java.net.URLConnection
67   * @see     java.net.URLConnection#getContent()
68   * @see     java.net.URLConnection#setContentHandlerFactory(java.net.ContentHandlerFactory)
69   * @since   JDK1.0
70   */
71  abstract public class ContentHandler {
72      /**
73       * Given a URL connect stream positioned at the beginning of the
74       * representation of an object, this method reads that stream and
75       * creates an object from it.
76       *
77       * @param      urlc   a URL connection.
78       * @return     the object read by the {@code ContentHandler}.
79       * @exception  IOException  if an I/O error occurs while reading the object.
80       */
81      abstract public Object getContent(URLConnection urlc) throws IOException;
82  
83      /**
84       * Given a URL connect stream positioned at the beginning of the
85       * representation of an object, this method reads that stream and
86       * creates an object that matches one of the types specified.
87       *
88       * The default implementation of this method should call getContent()
89       * and screen the return type for a match of the suggested types.
90       *
91       * @param      urlc   a URL connection.
92       * @param      classes      an array of types requested
93       * @return     the object read by the {@code ContentHandler} that is
94       *                 the first match of the suggested types.
95       *                 null if none of the requested  are supported.
96       * @exception  IOException  if an I/O error occurs while reading the object.
97       * @since 1.3
98       */
99      @SuppressWarnings("rawtypes")
100     public Object getContent(URLConnection urlc, Class[] classes) throws IOException {
101         Object obj = getContent(urlc);
102 
103         for (int i = 0; i < classes.length; i++) {
104           if (classes[i].isInstance(obj)) {
105                 return obj;
106           }
107         }
108         return null;
109     }
110 
111 }