1/*
2 * Copyright (c) 2015, 2017, 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
26/**
27 * Provides SAX specific transformation classes.
28 *
29 * <p>
30 * The {@link javax.xml.transform.sax.SAXSource} class allows the
31 * setting of an {@link org.xml.sax.XMLReader} to be used for pulling
32 * parse events, and an {@link org.xml.sax.InputSource} that may be used to
33 * specify the SAX source.
34 * <p>
35 * The {@link javax.xml.transform.sax.SAXResult} class allows the
36 * setting of a {@link org.xml.sax.ContentHandler} to be the receiver of
37 * SAX2 events from the transformation.
38 * <p>
39 * The {@link javax.xml.transform.sax.SAXTransformerFactory} extends
40 * {@link javax.xml.transform.TransformerFactory} to provide factory
41 * methods for creating {@link javax.xml.transform.sax.TemplatesHandler},
42 * {@link javax.xml.transform.sax.TransformerHandler}, and
43 * {@link org.xml.sax.XMLReader} instances.
44 * <p>
45 * To obtain a {@link javax.xml.transform.sax.SAXTransformerFactory},
46 * the caller must cast the {@link javax.xml.transform.TransformerFactory}
47 * instance returned from
48 * {@link javax.xml.transform.TransformerFactory#newInstance}.
49 *
50 * <p>
51 * The {@link javax.xml.transform.sax.TransformerHandler} interface
52 * allows a transformation to be created from SAX2 parse events, which is a "push"
53 * model rather than the "pull" model that normally occurs for a transformation.
54 * Normal parse events are received through the
55 * {@link org.xml.sax.ContentHandler} interface, lexical events such as
56 * startCDATA and endCDATA are received through the
57 * {@link org.xml.sax.ext.LexicalHandler} interface, and events that signal
58 * the start or end of disabling output escaping are received via
59 * {@link org.xml.sax.ContentHandler#processingInstruction}, with the
60 * target parameter being
61 * {@link javax.xml.transform.Result#PI_DISABLE_OUTPUT_ESCAPING} and
62 * {@link javax.xml.transform.Result#PI_ENABLE_OUTPUT_ESCAPING}. If
63 * parameters, output properties, or other features need to be set on the
64 * Transformer handler, a {@link javax.xml.transform.Transformer} reference
65 * will need to be obtained from
66 * {@link javax.xml.transform.sax.TransformerHandler#getTransformer}, and
67 * the methods invoked from that reference.
68 *
69 * <p>
70 * The {@link javax.xml.transform.sax.TemplatesHandler} interface
71 * allows the creation of {@link javax.xml.transform.Templates} objects
72 * from SAX2 parse events. Once the {@link org.xml.sax.ContentHandler}
73 * events are complete, the Templates object may be obtained from
74 * {@link javax.xml.transform.sax.TemplatesHandler#getTemplates}. Note that
75 * {@link javax.xml.transform.sax.TemplatesHandler#setSystemId} should
76 * normally be called in order to establish a base system ID from which relative
77 * URLs may be resolved.
78 * <p>
79 * The {@link javax.xml.transform.sax.SAXTransformerFactory#newXMLFilter}
80 * method allows the creation of a {@link org.xml.sax.XMLFilter}, which
81 * encapsulates the SAX2 notion of a "pull" transformation. The resulting
82 * {@code XMLFilters} can be chained together so that a series of transformations
83 * can happen with one's output becoming another's input.
84 *
85 * @since 1.5
86 */
87
88package javax.xml.transform.sax;
89