ContentHandler is the superclass of all classes that read an Object from a URLConnection. An application does not generally call the getContent method in this class directly. Instead, an application calls the getContent method in class URL or in URLConnection. The application's content handler factory (an instance of a class that implements the interface ContentHandlerFactory set up by a call to setContentHandler) is called with a String giving the MIME type of the object being received on the socket. The factory returns an instance of a subclass of ContentHandler, and its getContent method is called to create the object.
If no content handler could be found, URLConnection will look for a content handler in a user-defineable set of places. By default it looks in sun.net.www.content, but users can define a vertical-bar delimited set of class prefixes to search through in addition by defining the java.content.handler.pkgs property. The class name must be of the form:
{package-prefix}.{major}.{minor} e.g. YoyoDyne.experimental.text.plain If the loading of the content handler class would be performed by a classloader that is outside of the delegation chain of the caller, the JVM will need the RuntimePermission "getClassLoader".
@author James Gosling
@version 1.20, 04/07/06
@see java.net.ContentHandler#getContent(java.net.URLConnection)
@see java.net.ContentHandlerFactory
@see java.net.URL#getContent()
@see java.net.URLConnection
@see java.net.URLConnection#getContent()
@see java.net.URLConnection#setContentHandlerFactory(java.net.ContentHandlerFactory)
@since JDK1.0
A content handler can declare a set of suffixes that identify content it can handle based on the syntax of a URL. The suffix is a case-insensitive string that includes punctuation, for example ".png". For some URLs and content storage mechanisms, such as file systems, the content type is not readily available. To accommodate this, a mapping can be used to associate URL suffixes with content handlers. The common practice in file systems is to map filename extensions to content types. For example, a file ending in .png can be identified as content type image/png. This mapping is used if the content access mechanism does not support content typing or if the content type is not available from the content. For the http protocol, that supports a mechanism to identify the content type, the suffix matching MUST be used to identify content handlers if the type is not defined for a particular URL. RFC 2396 - Uniform Resource Identifiers (URI): Generic Syntax describes the syntax of URI's and the path component. Suffix matching consists of comparing each of the registered suffixes with the last n characters of the path component of the URL, where n is the length of the suffix. The comparison is case-insensitive and is done using the equivalent of java.lang.String.regionMatches. If multiple suffixes would match, the longest suffix that matches is used.
Each content handler registers a set of actions it supports. Actions are Java strings representing semantic functions the content handler can perform on every content type and suffix registered. Actions are case-sensitive strings. The set of actions is extensible but applications should choose from the following actions when appropriate: {@link ContentHandler#ACTION_OPEN open}, {@link ContentHandler#ACTION_EDIT edit}, {@link ContentHandler#ACTION_NEW new}, {@link ContentHandler#ACTION_SEND send}, {@link ContentHandler#ACTION_SAVE save}, {@link ContentHandler#ACTION_EXECUTE execute}, {@link ContentHandler#ACTION_SELECT select}, {@link ContentHandler#ACTION_INSTALL install}, {@link ContentHandler#ACTION_PRINT print}, and {@link ContentHandler#ACTION_STOP stop}.
The content handler application should provide localized action names for each action. The action names are used by applications that need to present the possible actions to users in locale appropriate terminology. A mapping for each action to action name should be created for each locale using the {@link ActionNameMap#ActionNameMap ActionNameMap.ActionNameMap} method.The action name maps for all the locales supported by the content handler MUST be included when the content handler is registered. The attribute Microedition-Handler-<n>-<locale> is used to declare action names in the application packaging.
A locale string MUST include a language code, and may include a country code and a variant. The values are separated by a delimiter defined by the Java runtime environment. For MIDP, locale strings follow the definition of the system property microedition.locale and the delimiter MUST be a hyphen ("-" = U+002D). The values for the language, country code and variant are not validated.
Application developers should refer to ISO-639-1 for language codes and to ISO-3166-1 for country codes.
Receives notifications of the content of a plain RFC822 or MIME message. Implement this interface and register an instance of that implementation with a MimeStreamParser instance using its {@link org.apache.james.mime4j.parser.MimeStreamParser#setContentHandler(ContentHandler)}method. The parser uses the ContentHandler instance to report basic message-related events like the start and end of the body of a part in a multipart MIME entity.
Throwing an exception from an event method will terminate the message processing, i.e. no new events will be generated for that message.
Events will be generated in the order the corresponding elements occur in the message stream parsed by the parser. E.g.:
startMessage() startHeader() field(...) field(...) ... endHeader() startMultipart() preamble(...) startBodyPart() startHeader() field(...) field(...) ... endHeader() body() endBodyPart() startBodyPart() startHeader() field(...) field(...) ... endHeader() body() endBodyPart() epilogue(...) endMultipart() endMessage()The above shows an example of a MIME message consisting of a multipart body containing two body parts.
See MIME RFCs 2045-2049 for more information on the structure of MIME messages and RFC 822 and 2822 for the general structure of Internet mail messages.
A content handler is used primarily by a {@link URIConverter URI converter}which provides support for {@link URIConverter#contentDescription(URI,Map) describing} the contents of a URIby virtue of having a {@link URIConverter#getContentHandlers() list} of content handlersthat it consults to determine whether the handler {@link #canHandle(URI) can handle} the given URI and if sothat it uses as a delegate for computing the {@link #contentDescription(URI,InputStream,Map,Map) content description}.
@see URIHandler @see URIConverter @since 2.4This is the main interface that most SAX applications implement: if the application needs to be informed of basic parsing events, it implements this interface and registers an instance with the SAX parser using the {@link org.xml.sax.XMLReader#setContentHandler setContentHandler} method. The parser uses the instance to report basic document-related events like the start and end of elements and character data.
The order of events in this interface is very important, and mirrors the order of information in the document itself. For example, all of an element's content (character data, processing instructions, and/or subelements) will appear, in order, between the startElement event and the corresponding endElement event.
This interface is similar to the now-deprecated SAX 1.0 DocumentHandler interface, but it adds support for Namespaces and for reporting skipped entities (in non-validating XML processors).
Implementors should note that there is also a ContentHandler class in the java.net package; that means that it's probably a bad idea to do
import java.net.*; import org.xml.sax.*;
In fact, "import ...*" is usually a sign of sloppy programming anyway, so the user should consider this a feature rather than a bug.
@since SAX 2.0 @author David Megginson @version 2.0.1+ (sax2r3pre1) @see org.xml.sax.XMLReader @see org.xml.sax.DTDHandler @see org.xml.sax.ErrorHandler | |