ContentHandler.java revision 12745:f068a4ffddd2
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 26package java.net; 27 28import 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 {@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 */ 84public 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 */ 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 getContent() 103 * and screen the return type for a match of the suggested types. 104 * 105 * @param urlc a URL connection. 106 * @param classes an array of types requested 107 * @return the object read by the {@code ContentHandler} that is 108 * the first match of the suggested types or 109 * {@code null} if none of the requested are supported. 110 * @exception IOException if an I/O error occurs while reading the object. 111 * @since 1.3 112 */ 113 @SuppressWarnings("rawtypes") 114 public Object getContent(URLConnection urlc, Class[] classes) throws IOException { 115 Object obj = getContent(urlc); 116 117 for (Class<?> c : classes) { 118 if (c.isInstance(obj)) { 119 return obj; 120 } 121 } 122 return null; 123 } 124} 125