< prev index next >

src/java.base/share/classes/java/net/ContentHandler.java

Print this page




  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 }
< prev index next >