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 up by a call to 41 * {@link URLConnection#setContentHandlerFactory(ContentHandlerFactory) 42 * setContentHandlerFactory} is called with a {@code String} giving the 43 * MIME type of the 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 {@linkplain URLConnection#getContent() found}, 48 * URLConnection will look for a content handler in a user-definable set of places. 49 * Users can define a vertical-bar delimited set of class prefixes 50 * to search through by defining the <i>{@link java.net.URLConnection#contentPathProp}</i> 51 * property. The class name must be of the form: 52 * <blockquote> 53 * <i>{package-prefix}.{major}.{minor}</i> 54 * <p> 55 * where <i>{major}.{minor}</i> is formed by taking the 56 * content-type string, replacing all slash characters with a 57 * {@code period} ('.'), and all other non-alphanumeric characters 58 * with the underscore character '{@code _}'. The alphanumeric 59 * characters are specifically the 26 uppercase ASCII letters 60 * '{@code A}' through '{@code Z}', the 26 lowercase ASCII 61 * letters '{@code a}' through '{@code z}', and the 10 ASCII 62 * digits '{@code 0}' through '{@code 9}'. 63 * <p> 64 * e.g. 65 * YoyoDyne.experimental.text.plain 66 * </blockquote> 67 * If no user-defined content handler is found, then the system 68 * tries to load a specific <i>content-type</i> handler from one 69 * of the built-in handlers, if one exists. 70 * <p> 71 * If the loading of the content handler class would be performed by 72 * a classloader that is outside of the delegation chain of the caller, 73 * the JVM will need the RuntimePermission "getClassLoader". 74 * 75 * @author James Gosling 76 * @see java.net.ContentHandler#getContent(java.net.URLConnection) 77 * @see java.net.ContentHandlerFactory 78 * @see java.net.URL#getContent() 79 * @see java.net.URLConnection 80 * @see java.net.URLConnection#getContent() 81 * @see java.net.URLConnection#setContentHandlerFactory(java.net.ContentHandlerFactory) 82 * @since 1.0 83 */ 84 public abstract class ContentHandler { 85 86 /** 87 * Given a URL connect stream positioned at the beginning of the 88 * representation of an object, this method reads that stream and 89 * creates an object from it. 90 * 91 * @param urlc a URL connection. 92 * @return the object read by the {@code ContentHandler}. 93 * @exception IOException if an I/O error occurs while reading the object. 94 */ getContent(URLConnection urlc)95 public abstract Object getContent(URLConnection urlc) throws IOException; 96 97 /** 98 * Given a URL connect stream positioned at the beginning of the 99 * representation of an object, this method reads that stream and 100 * creates an object that matches one of the types specified. 101 * 102 * The default implementation of this method should call 103 * {@link #getContent(URLConnection)} 104 * and screen the return type for a match of the suggested types. 105 * 106 * @param urlc a URL connection. 107 * @param classes an array of types requested 108 * @return the object read by the {@code ContentHandler} that is 109 * the first match of the suggested types or 110 * {@code null} if none of the requested are supported. 111 * @exception IOException if an I/O error occurs while reading the object. 112 * @since 1.3 113 */ 114 @SuppressWarnings("rawtypes") getContent(URLConnection urlc, Class[] classes)115 public Object getContent(URLConnection urlc, Class[] classes) throws IOException { 116 Object obj = getContent(urlc); 117 118 for (Class<?> c : classes) { 119 if (c.isInstance(obj)) { 120 return obj; 121 } 122 } 123 return null; 124 } 125 } 126