Source code: com/hp/hpl/jena/rdf/arp/SAX2RDF.java
1 /*
2 * (c) Copyright 2004, 2005 Hewlett-Packard Development Company, LP
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright
11 * notice, this list of conditions and the following disclaimer in the
12 * documentation and/or other materials provided with the distribution.
13 * 3. The name of the author may not be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26
27 * * $Id: SAX2RDF.java,v 1.11 2005/04/15 10:43:55 jeremy_carroll Exp $
28
29 AUTHOR: Jeremy J. Carroll
30 */
31 package com.hp.hpl.jena.rdf.arp;
32 import org.xml.sax.*;
33
34 /**
35 * <p>
36 * Allows connecting an arbitrary source of SAX events with ARP.
37 * </p>
38 * <p>For use with a DOM tree,
39 * see <a href="http://javaalmanac.com/egs/javax.xml.transform.sax/Dom2Sax.html">
40 * The Java Developer's Almanac</a> for a discussion of how to transform a DOM
41 * into a source of SAX events.
42 * </p>
43 *
44 * <p>
45 * The use pattern is to create and initialize one of these,
46 * then set it as the content, lexical and error handler
47 * for some source of SAX events (e.g. from a parser).
48 * It must be configured to use namespaces, and namespace
49 * prefixes. This initializing can be done for XMLReaders
50 * using {@link #installHandlers}.
51 * </p>
52 * <p>
53 * Triples and errors are reported on a different thread.
54 * Do not expect synchronous behaviour between the SAX events
55 * and the triples or errors being generated.
56 * </p>
57 * <p>
58 * This class does not support multithreaded SAX sources, nor IO interruption.
59 * </p>
60 * <p>
61 * There is further documentation:
62 * <a href="../../../../../../../ARP/standalone.html#not-jena">here</a>
63 * and
64 * <a href="../../../../../../../ARP/sax.html#sax2rdf">here</a>.
65 * </p>
66 * @author Jeremy Carroll
67 * */
68 public class SAX2RDF extends SAX2RDFImpl
69 implements ARPConfig {
70 /**
71 * Factory method to create a new SAX2RDF.
72 * Use
73 * {@link #getHandlers} or {@link #setHandlersWith} to provide
74 * a {@link StatementHandler}, and usually an {@link org.xml.sax.ErrorHandler}
75 *
76 * @param base The retrieval URL, or the base URI to be
77 * used while parsing.
78 * @return A new SAX2RDF
79 * @throws MalformedURIException
80 */
81 static public SAX2RDF newInstance(String base) throws MalformedURIException {
82 return new SAX2RDF(base,"");
83 }
84 /**
85 * Factory method to create a new SAX2RDF.
86 * This is particularly
87 * intended for when parsing a non-root element within
88 * an XML document. In which case the application
89 * needs to find this value in the outer context.
90 * Optionally, namespace prefixes can be passed from the
91 * outer context using {@link #startPrefixMapping}.
92 * @param base The retrieval URL, or the base URI to be
93 * used while parsing. Use
94 * {@link #getHandlers} or {@link #setHandlersWith} to provide
95 * a {@link StatementHandler}, and usually an {@link org.xml.sax.ErrorHandler}
96 * @param lang The current value of xml:lang when parsing starts, usually "".
97 * @return A new SAX2RDF
98 * @throws MalformedURIException If base is bad.
99 */
100 static public SAX2RDF newInstance(String base, String lang) throws MalformedURIException {
101 return new SAX2RDF(base,lang);
102 }
103 /**
104 * Begin the scope of a prefix-URI Namespace mapping.
105 *
106 *<p>This is passed to any {@link NamespaceHandler} associated
107 *with this parser.
108 *It can be called before the initial
109 *{@link #startElement} event, or other events associated
110 *with the elements being processed.
111 *When building a Jena Model, it is not required to match this
112 *with corresponding {@link #endPrefixMapping} events.
113 *Other {@link NamespaceHandler}s may be fussier.
114 *When building a Jena Model, the prefix bindings are
115 *remembered with the Model, and may be used in some
116 *output routines. It is permitted to not call this method
117 *for prefixes declared in the outer context, in which case,
118 *any output routine will need to use a gensym for such
119 *namespaces.
120 *</p>
121 * @param prefix The Namespace prefix being declared.
122 * @param uri The Namespace URI the prefix is mapped to.
123 *
124 */
125 public void startPrefixMapping (String prefix, String uri)
126 { super.startPrefixMapping(prefix,uri);
127 }
128
129 SAX2RDF(String base, String lang) throws MalformedURIException {
130 super(base,lang);
131 initParse(base);
132 }
133 /** This is used when configuring a parser that
134 * is not loading into a Jena Model, but is processing
135 * the triples etc. in some other way.
136
137 * @see com.hp.hpl.jena.rdf.arp.ARPConfig#getHandlers()
138 */
139 public ARPHandlers getHandlers() {
140 return super.getHandlers();
141 }
142 /** This is used when configuring a parser that
143 * is not loading into a Jena Model, but is processing
144 * the triples etc. in some other way.
145
146 * @see com.hp.hpl.jena.rdf.arp.ARPConfig#setHandlersWith(com.hp.hpl.jena.rdf.arp.ARPHandlers)
147 */
148 public void setHandlersWith(ARPHandlers handlers) {
149 super.setHandlersWith(handlers);
150 }
151 /* (non-Javadoc)
152 * @see com.hp.hpl.jena.rdf.arp.ARPConfig#getOptions()
153 */
154 public ARPOptions getOptions() {
155 return super.getOptions();
156 }
157 /* (non-Javadoc)
158 * @see com.hp.hpl.jena.rdf.arp.ARPConfig#setOptions(com.hp.hpl.jena.rdf.arp.ARPOptions)
159 */
160 public void setOptionsWith(ARPOptions opts) {
161 super.setOptionsWith(opts);
162
163 }
164 /**
165 * Initializes an XMLReader to use the SAX2RDF object
166 * as its handler for all events, and to use namespaces
167 * and namespace prefixes.
168 * @param rdr The XMLReader to initialize.
169 * @param sax2rdf The SAX2RDF instance to use.
170 */
171 static public void installHandlers(XMLReader rdr, XMLHandler sax2rdf)
172 throws SAXException
173 {
174 rdr.setEntityResolver(sax2rdf);
175 rdr.setDTDHandler(sax2rdf);
176 rdr.setContentHandler(sax2rdf);
177 rdr.setErrorHandler(sax2rdf);
178 rdr.setFeature("http://xml.org/sax/features/namespaces", true);
179 rdr.setFeature(
180 "http://xml.org/sax/features/namespace-prefixes",
181 true);
182 rdr.setProperty(
183 "http://xml.org/sax/properties/lexical-handler",
184 sax2rdf);
185 rdr.setFeature(
186 "http://apache.org/xml/features/allow-java-encodings",true);
187
188 }
189 }
190
191