001: /*
002: * (c) Copyright 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
003: * All rights reserved.
004: *
005: * Redistribution and use in source and binary forms, with or without
006: * modification, are permitted provided that the following conditions
007: * are met:
008: * 1. Redistributions of source code must retain the above copyright
009: * notice, this list of conditions and the following disclaimer.
010: * 2. Redistributions in binary form must reproduce the above copyright
011: * notice, this list of conditions and the following disclaimer in the
012: * documentation and/or other materials provided with the distribution.
013: * 3. The name of the author may not be used to endorse or promote products
014: * derived from this software without specific prior written permission.
015:
016: * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
017: * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
018: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
019: * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
020: * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
021: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
022: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
023: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
024: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
025: * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
026:
027: * * $Id: SAX2RDF.java,v 1.20 2008/01/02 12:06:46 andy_seaborne Exp $
028:
029: AUTHOR: Jeremy J. Carroll
030: */
031: package com.hp.hpl.jena.rdf.arp;
032:
033: import org.xml.sax.SAXException;
034: import org.xml.sax.SAXParseException;
035: import org.xml.sax.XMLReader;
036:
037: import com.hp.hpl.jena.rdf.arp.impl.SAX2RDFImpl;
038: import com.hp.hpl.jena.rdf.arp.impl.XMLHandler;
039:
040: /**
041: * <p>
042: * Allows connecting an arbitrary source of SAX events with ARP.
043: * </p>
044: * <p>For use with a DOM tree,
045: * either use {@link DOM2Model} or
046: * see <a href="http://javaalmanac.com/egs/javax.xml.transform.sax/Dom2Sax.html">
047: * The Java Developer's Almanac</a> for a discussion of how to transform a DOM
048: * into a source of SAX events.
049: * </p>
050: *
051: * <p>
052: * The use pattern is to create and initialize one of these,
053: * then set it as the content, lexical and error handler
054: * for some source of SAX events (e.g. from a parser).
055: * The parser must be configured to use namespaces, and namespace
056: * prefixes. This initializing can be done for XMLReaders
057: * using {@link #installHandlers}.
058: * </p>
059: *
060: * <p>
061: * To build a Jena model it is better to use {@link SAX2Model}.
062: * The documentation here, covers usage both using the subclass
063: * {@link SAX2Model}, and not.
064: * </p>
065: * <p>
066: * This class does not support multithreaded SAX sources, nor IO interruption.
067: * </p>
068: * <p>
069: * There is further documentation:
070: * <a href="../../../../../../../ARP/standalone.html#not-jena">here</a>
071: * and
072: * <a href="../../../../../../../ARP/sax.html#sax2rdf">here</a>.
073: * </p>
074: * @author Jeremy Carroll
075: * */
076: public class SAX2RDF extends SAX2RDFImpl implements ARPConfig {
077: /**
078: * Factory method to create a new SAX2RDF.
079: * Use
080: * {@link #getHandlers} or {@link #setHandlersWith} to provide
081: * a {@link StatementHandler}, and usually an {@link org.xml.sax.ErrorHandler}
082: *
083: * @param base The retrieval URL, or the base URI to be
084: * used while parsing.
085: * @deprecated Use {@link #create(String)}.
086: * @return A new SAX2RDF
087: * @throws MalformedURIException
088: */
089: static public SAX2RDF newInstance(String base)
090: throws MalformedURIException {
091: try {
092: return create(base);
093: } catch (SAXParseException e) {
094: throw new MalformedURIException(e.getMessage());
095: }
096: }
097:
098: /**
099: * Factory method to create a new SAX2RDF.
100: * This is particularly
101: * intended for when parsing a non-root element within
102: * an XML document. In which case the application
103: * needs to find this value in the outer context.
104: * Optionally, namespace prefixes can be passed from the
105: * outer context using {@link #startPrefixMapping}.
106: * @param base The retrieval URL, or the base URI to be
107: * used while parsing. Use
108: * {@link #getHandlers} or {@link #setHandlersWith} to provide
109: * a {@link StatementHandler}, and usually an {@link org.xml.sax.ErrorHandler}
110: * @param lang The current value of xml:lang when parsing starts, usually "".
111: * @return A new SAX2RDF
112: * @throws MalformedURIException If base is bad.
113: * @deprecated Use {@link #create(String,String)}.
114: */
115: static public SAX2RDF newInstance(String base, String lang)
116: throws MalformedURIException {
117: try {
118: return create(base, lang);
119: } catch (SAXParseException e) {
120: throw new MalformedURIException(e.getMessage());
121: }
122:
123: }
124:
125: /**
126: * Factory method to create a new SAX2RDF.
127: * Use
128: * {@link #getHandlers} or {@link #setHandlersWith} to provide
129: * a {@link StatementHandler}, and usually an {@link org.xml.sax.ErrorHandler}
130: *
131: * @param base The retrieval URL, or the base URI to be
132: * used while parsing.
133: * @return A new SAX2RDF
134: * @throws ParseException
135: */
136: static public SAX2RDF create(String base) throws SAXParseException {
137: return new SAX2RDF(base, "");
138: }
139:
140: /**
141: * Factory method to create a new SAX2RDF.
142: * This is particularly
143: * intended for when parsing a non-root element within
144: * an XML document. In which case the application
145: * needs to find this value in the outer context.
146: * Optionally, namespace prefixes can be passed from the
147: * outer context using {@link #startPrefixMapping}.
148: * @param base The retrieval URL, or the base URI to be
149: * used while parsing. Use
150: * {@link #getHandlers} or {@link #setHandlersWith} to provide
151: * a {@link StatementHandler}, and usually an {@link org.xml.sax.ErrorHandler}
152: * @param lang The current value of xml:lang when parsing starts, usually "".
153: * @return A new SAX2RDF
154: * @throws ParseException If base or lang is bad.
155: */
156: static public SAX2RDF create(String base, String lang)
157: throws SAXParseException {
158: return new SAX2RDF(base, lang);
159: }
160:
161: /**
162: * Begin the scope of a prefix-URI Namespace mapping.
163: *
164: *<p>This is passed to any {@link NamespaceHandler} associated
165: *with this parser.
166: *It can be called before the initial
167: *<code>startElement</code> event, or other events associated
168: *with the elements being processed.
169: *When building a Jena Model, with {@link SAX2Model} it is not required to match this
170: *with corresponding <code>endPrefixMapping</code> events.
171: *Other {@link NamespaceHandler}s may be fussier.
172: *When building a Jena Model, the prefix bindings are
173: *remembered with the Model, and may be used in some
174: *output routines. It is permitted to not call this method
175: *for prefixes declared in the outer context, in which case,
176: *any output routine will need to use a gensym for such
177: *namespaces.
178: *</p>
179: * @param prefix The Namespace prefix being declared.
180: * @param uri The Namespace URI the prefix is mapped to.
181: *
182: */
183: public void startPrefixMapping(String prefix, String uri)
184: throws SAXParseException {
185: super .startPrefixMapping(prefix, uri);
186: }
187:
188: SAX2RDF(String base, String lang) throws SAXParseException {
189: super (base, lang);
190:
191: initParse(base);
192: }
193:
194: /**
195: * @deprecated
196: */
197: void initParseX(String base, String lang)
198: throws MalformedURIException {
199: try {
200: initParse(base, lang);
201: } catch (SAXParseException e) {
202: throw new MalformedURIException(e);
203: }
204: }
205:
206: /**
207: * Must call initParse after this.
208: * @deprecated
209: */
210: SAX2RDF(String base, String lang, boolean dummy) {
211: super (base, lang);
212:
213: }
214:
215: /**The handlers used for processing ARP events.
216: * Do not use with a {@link SAX2Model}.
217:
218: * @see com.hp.hpl.jena.rdf.arp.ARPConfig#getHandlers()
219: */
220: public ARPHandlers getHandlers() {
221: return super .getHandlers();
222: }
223:
224: /**Copys handlers used for processing ARP events.
225: * Do not use with a {@link SAX2Model}.
226:
227: * @see com.hp.hpl.jena.rdf.arp.ARPConfig#setHandlersWith(ARPHandlers)
228: */
229: public void setHandlersWith(ARPHandlers handlers) {
230: super .setHandlersWith(handlers);
231: }
232:
233: /* (non-Javadoc)
234: * @see com.hp.hpl.jena.rdf.arp.ARPConfig#getOptions()
235: */
236: public ARPOptions getOptions() {
237: return super .getOptions();
238: }
239:
240: /* (non-Javadoc)
241: * @see com.hp.hpl.jena.rdf.arp.ARPConfig#setOptions(com.hp.hpl.jena.rdf.arp.ARPOptions)
242: */
243: public void setOptionsWith(ARPOptions opts) {
244: super .setOptionsWith(opts);
245:
246: }
247:
248: /**
249: * Initializes an XMLReader to use the SAX2RDF object
250: * as its handler for all events, and to use namespaces
251: * and namespace prefixes.
252: * @param rdr The XMLReader to initialize.
253: * @param sax2rdf The SAX2RDF instance to use.
254: */
255: static public void installHandlers(XMLReader rdr, XMLHandler sax2rdf)
256: throws SAXException {
257: rdr.setEntityResolver(sax2rdf);
258: rdr.setDTDHandler(sax2rdf);
259: rdr.setContentHandler(sax2rdf);
260: rdr.setErrorHandler(sax2rdf);
261: rdr.setFeature("http://xml.org/sax/features/namespaces", true);
262: rdr
263: .setFeature(
264: "http://xml.org/sax/features/namespace-prefixes",
265: false);
266: rdr.setProperty(
267: "http://xml.org/sax/properties/lexical-handler",
268: sax2rdf);
269: rdr.setFeature(
270: "http://apache.org/xml/features/allow-java-encodings",
271: true);
272:
273: }
274: }
|