151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/* 23a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. 351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is free software; you can redistribute it and/or modify it 651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * under the terms of the GNU General Public License version 2 only, as 751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * published by the Free Software Foundation. Oracle designates this 851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * particular file as subject to the "Classpath" exception as provided 951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by Oracle in the LICENSE file that accompanied this code. 1051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is distributed in the hope that it will be useful, but WITHOUT 1251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * version 2 for more details (a copy is included in the LICENSE file that 1551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * accompanied this code). 1651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * You should have received a copy of the GNU General Public License version 1851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2 along with this work; if not, write to the Free Software Foundation, 1951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or visit www.oracle.com if you need additional information or have any 2351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * questions. 2451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 2551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 2651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipackage java.net; 2751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 2851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.io.IOException; 2951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 3051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/** 313a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * The abstract class {@code ContentHandler} is the superclass 323a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * of all classes that read an {@code Object} from a 333a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * {@code URLConnection}. 3451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> 3551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * An application does not generally call the 363a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * {@code getContent} method in this class directly. Instead, an 373a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * application calls the {@code getContent} method in class 383a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * {@code URL} or in {@code URLConnection}. 3951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The application's content handler factory (an instance of a class that 403a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * implements the interface {@code ContentHandlerFactory} set 413a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * up by a call to {@code setContentHandler}) is 423a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * called with a {@code String} giving the MIME type of the 4351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * object being received on the socket. The factory returns an 443a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * instance of a subclass of {@code ContentHandler}, and its 453a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * {@code getContent} method is called to create the object. 4651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> 4751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If no content handler could be found, URLConnection will 4851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * look for a content handler in a user-defineable set of places. 4951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * By default it looks in sun.net.www.content, but users can define a 5051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * vertical-bar delimited set of class prefixes to search through in 5151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * addition by defining the java.content.handler.pkgs property. 5251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The class name must be of the form: 5351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <pre> 5451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {package-prefix}.{major}.{minor} 5551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * e.g. 5651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * YoyoDyne.experimental.text.plain 5751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </pre> 5851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the loading of the content handler class would be performed by 5951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * a classloader that is outside of the delegation chain of the caller, 6051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the JVM will need the RuntimePermission "getClassLoader". 6151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 6251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @author James Gosling 6351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see java.net.ContentHandler#getContent(java.net.URLConnection) 6451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see java.net.ContentHandlerFactory 6551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see java.net.URL#getContent() 6651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see java.net.URLConnection 6751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see java.net.URLConnection#getContent() 6851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see java.net.URLConnection#setContentHandlerFactory(java.net.ContentHandlerFactory) 6951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since JDK1.0 7051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 7151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiabstract public class ContentHandler { 7251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 7351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Given a URL connect stream positioned at the beginning of the 7451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * representation of an object, this method reads that stream and 7551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * creates an object from it. 7651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 7751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param urlc a URL connection. 783a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * @return the object read by the {@code ContentHandler}. 7951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @exception IOException if an I/O error occurs while reading the object. 8051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 8151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski abstract public Object getContent(URLConnection urlc) throws IOException; 8251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 8351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 8451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Given a URL connect stream positioned at the beginning of the 8551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * representation of an object, this method reads that stream and 8651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * creates an object that matches one of the types specified. 8751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 8851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The default implementation of this method should call getContent() 8951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and screen the return type for a match of the suggested types. 9051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 9151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param urlc a URL connection. 9251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param classes an array of types requested 933a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong * @return the object read by the {@code ContentHandler} that is 9451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the first match of the suggested types. 9551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * null if none of the requested are supported. 9651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @exception IOException if an I/O error occurs while reading the object. 9751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since 1.3 9851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 993a6411ec91b24e73f36301d0075bc7b052894ae9Yi Kong @SuppressWarnings("rawtypes") 10051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public Object getContent(URLConnection urlc, Class[] classes) throws IOException { 10151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski Object obj = getContent(urlc); 10251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 10351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski for (int i = 0; i < classes.length; i++) { 10451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski if (classes[i].isInstance(obj)) { 10551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return obj; 10651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 10751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 10851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return null; 10951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 11051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 11151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski} 112