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 * Users can define a vertical-bar delimited set of class prefixes 50 * to search through by defining the <i>java.content.handler.pkgs</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 abstract public class ContentHandler { 85 /** 86 * Given a URL connect stream positioned at the beginning of the 87 * representation of an object, this method reads that stream and 88 * creates an object from it. 89 * 90 * @param urlc a URL connection. 91 * @return the object read by the {@code ContentHandler}. 92 * @exception IOException if an I/O error occurs while reading the object. 93 */ 94 abstract public Object getContent(URLConnection urlc) throws IOException; 95 96 /** 97 * Given a URL connect stream positioned at the beginning of the 98 * representation of an object, this method reads that stream and 99 * creates an object that matches one of the types specified. 100 * 101 * The default implementation of this method should call getContent() 102 * and screen the return type for a match of the suggested types. 103 * 104 * @param urlc a URL connection. 105 * @param classes an array of types requested 106 * @return the object read by the {@code ContentHandler} that is 107 * the first match of the suggested types. 108 * null if none of the requested are supported. 109 * @exception IOException if an I/O error occurs while reading the object. 110 * @since 1.3 111 */ 112 @SuppressWarnings("rawtypes") 113 public Object getContent(URLConnection urlc, Class[] classes) throws IOException { 114 Object obj = getContent(urlc); 115 116 for (int i = 0; i < classes.length; i++) { 117 if (classes[i].isInstance(obj)) { 118 return obj; 119 } 120 } 121 return null; 122 } 123 124 } | 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 {@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>{@value 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 abstract public 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 abstract public 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 } |