001: /*
002: * Copyright Aduna (http://www.aduna-software.com/) (c) 1997-2007.
003: *
004: * Licensed under the Aduna BSD-style license.
005: */
006: package org.openrdf.query.resultio;
007:
008: import java.io.IOException;
009: import java.io.InputStream;
010: import java.io.OutputStream;
011:
012: import org.openrdf.model.ValueFactory;
013: import org.openrdf.query.GraphQueryResult;
014: import org.openrdf.query.QueryEvaluationException;
015: import org.openrdf.query.QueryResultUtil;
016: import org.openrdf.query.TupleQueryResult;
017: import org.openrdf.query.TupleQueryResultHandler;
018: import org.openrdf.query.TupleQueryResultHandlerException;
019: import org.openrdf.query.impl.TupleQueryResultBuilder;
020: import org.openrdf.rio.RDFFormat;
021: import org.openrdf.rio.RDFHandlerException;
022: import org.openrdf.rio.RDFWriter;
023: import org.openrdf.rio.Rio;
024: import org.openrdf.rio.UnsupportedRDFormatException;
025:
026: /**
027: * Class offering utility methods related to query results.
028: *
029: * @author Arjohn Kampman
030: */
031: public class QueryResultIO {
032:
033: /**
034: * Tries to match a MIME type against the list of tuple query result formats
035: * that can be parsed.
036: *
037: * @param mimeType
038: * A MIME type, e.g. "application/sparql-results+xml".
039: * @return An RDFFormat object if a match was found, or <tt>null</tt>
040: * otherwise.
041: * @see #getParserFormatForMIMEType(String, RDFFormat)
042: */
043: public static TupleQueryResultFormat getParserFormatForMIMEType(
044: String mimeType) {
045: return TupleQueryResultParserRegistry.getInstance()
046: .getFileFormatForMIMEType(mimeType, null);
047: }
048:
049: /**
050: * Tries to match a MIME type against the list of tuple query result formats
051: * that can be parsed. This method calls
052: * {@link TupleQueryResultFormat#matchMIMEType(String, Iterable)} with the
053: * specified MIME type, the keys of
054: * {@link TupleQueryResultParserRegistry#getInstance()} and the fallback
055: * format as parameters.
056: *
057: * @param mimeType
058: * A MIME type, e.g. "application/sparql-results+xml".
059: * @param fallback
060: * The format that will be returned if no match was found.
061: * @return The matching TupleQueryResultFormat, or <tt>fallback</tt> if no
062: * match was found.
063: */
064: public static TupleQueryResultFormat getParserFormatForMIMEType(
065: String mimeType, TupleQueryResultFormat fallback) {
066: return TupleQueryResultParserRegistry.getInstance()
067: .getFileFormatForMIMEType(mimeType, fallback);
068: }
069:
070: /**
071: * Tries to match the extension of a file name against the list of RDF
072: * formats that can be parsed.
073: *
074: * @param fileName
075: * A file name.
076: * @return An TupleQueryResultFormat object if a match was found, or
077: * <tt>null</tt> otherwise.
078: * @see #getParserFormatForFileName(String, TupleQueryResultFormat)
079: */
080: public static TupleQueryResultFormat getParserFormatForFileName(
081: String fileName) {
082: return TupleQueryResultParserRegistry.getInstance()
083: .getFileFormatForFileName(fileName);
084: }
085:
086: /**
087: * Tries to match the extension of a file name against the list of RDF
088: * formats that can be parsed. This method calls
089: * {@link TupleQueryResultFormat#matchFileName(String, Iterable, info.aduna.lang.FileFormat)}
090: * with the specified MIME type, the keys of
091: * {@link TupleQueryResultParserRegistry#getInstance()} and the fallback
092: * format as parameters.
093: *
094: * @param fileName
095: * A file name.
096: * @param fallback
097: * The format that will be returned if no match was found.
098: * @return The matching TupleQueryResultFormat, or <tt>fallback</tt> if no
099: * match was found.
100: */
101: public static TupleQueryResultFormat getParserFormatForFileName(
102: String fileName, TupleQueryResultFormat fallback) {
103: return TupleQueryResultParserRegistry.getInstance()
104: .getFileFormatForFileName(fileName, fallback);
105: }
106:
107: /**
108: * Tries to match a MIME type against the list of tuple query result formats
109: * that can be written.
110: *
111: * @param mimeType
112: * A MIME type, e.g. "application/sparql-results+xml".
113: * @return An TupleQueryResultFormat object if a match was found, or
114: * <tt>null</tt> otherwise.
115: * @see #getWriterFormatForMIMEType(String, TupleQueryResultFormat)
116: */
117: public static TupleQueryResultFormat getWriterFormatForMIMEType(
118: String mimeType) {
119: return TupleQueryResultWriterRegistry.getInstance()
120: .getFileFormatForMIMEType(mimeType);
121: }
122:
123: /**
124: * Tries to match a MIME type against the list of tuple query result formats
125: * that can be written. This method calls
126: * {@link TupleQueryResultFormat#matchMIMEType(String, Iterable, info.aduna.lang.FileFormat)}
127: * with the specified MIME type, the keys of
128: * {@link TupleQueryResultWriterRegistry#getInstance()} and the fallback
129: * format as parameters.
130: *
131: * @param mimeType
132: * A MIME type, e.g. "application/sparql-results+xml".
133: * @param fallback
134: * The format that will be returned if no match was found.
135: * @return The matching TupleQueryResultFormat, or <tt>fallback</tt> if no
136: * match was found.
137: */
138: public static TupleQueryResultFormat getWriterFormatForMIMEType(
139: String mimeType, TupleQueryResultFormat fallback) {
140: return TupleQueryResultWriterRegistry.getInstance()
141: .getFileFormatForMIMEType(mimeType, fallback);
142: }
143:
144: /**
145: * Tries to match the extension of a file name against the list of RDF
146: * formats that can be written.
147: *
148: * @param fileName
149: * A file name.
150: * @return An TupleQueryResultFormat object if a match was found, or
151: * <tt>null</tt> otherwise.
152: * @see #getWriterFormatForFileName(String, TupleQueryResultFormat)
153: */
154: public static TupleQueryResultFormat getWriterFormatForFileName(
155: String fileName) {
156: return TupleQueryResultWriterRegistry.getInstance()
157: .getFileFormatForFileName(fileName);
158: }
159:
160: /**
161: * Tries to match the extension of a file name against the list of RDF
162: * formats that can be written. This method calls
163: * {@link TupleQueryResultFormat#matchFileName(String, Iterable, info.aduna.lang.FileFormat)}
164: * with the specified MIME type, the keys of
165: * {@link TupleQueryResultWriterRegistry#getInstance()} and the fallback
166: * format as parameters.
167: *
168: * @param fileName
169: * A file name.
170: * @param fallback
171: * The format that will be returned if no match was found.
172: * @return The matching TupleQueryResultFormat, or <tt>fallback</tt> if no
173: * match was found.
174: */
175: public static TupleQueryResultFormat getWriterFormatForFileName(
176: String fileName, TupleQueryResultFormat fallback) {
177: return TupleQueryResultWriterRegistry.getInstance()
178: .getFileFormatForFileName(fileName, fallback);
179: }
180:
181: /**
182: * Convenience methods for creating TupleQueryResultParser objects. This
183: * method uses the registry returned by
184: * {@link TupleQueryResultParserRegistry#getInstance()} to get a factory for
185: * the specified format and uses this factory to create the appropriate
186: * parser.
187: *
188: * @throws UnsupportedQueryResultFormatException
189: * If no parser is available for the specified tuple query result
190: * format.
191: */
192: public static TupleQueryResultParser createParser(
193: TupleQueryResultFormat format)
194: throws UnsupportedQueryResultFormatException {
195: TupleQueryResultParserFactory factory = TupleQueryResultParserRegistry
196: .getInstance().get(format);
197:
198: if (factory != null) {
199: return factory.getParser();
200: }
201:
202: throw new UnsupportedQueryResultFormatException(
203: "No parser factory available for tuple query result format "
204: + format);
205: }
206:
207: /**
208: * Convenience methods for creating TupleQueryResultParser objects that use
209: * the specified ValueFactory to create RDF model objects.
210: *
211: * @throws UnsupportedQueryResultFormatException
212: * If no parser is available for the specified tuple query result
213: * format.
214: * @see #createParser(TupleQueryResultFormat)
215: * @see TupleQueryResultParser#setValueFactory(ValueFactory)
216: */
217: public static TupleQueryResultParser createParser(
218: TupleQueryResultFormat format, ValueFactory valueFactory)
219: throws UnsupportedQueryResultFormatException {
220: TupleQueryResultParser parser = createParser(format);
221: parser.setValueFactory(valueFactory);
222: return parser;
223: }
224:
225: /**
226: * Convenience methods for creating TupleQueryResultWriter objects. This
227: * method uses the registry returned by
228: * {@link TupleQueryResultWriterRegistry#getInstance()} to get a factory for
229: * the specified format and uses this factory to create the appropriate
230: * writer.
231: *
232: * @throws UnsupportedQueryResultFormatException
233: * If no writer is available for the specified tuple query result
234: * format.
235: */
236: public static TupleQueryResultWriter createWriter(
237: TupleQueryResultFormat format, OutputStream out)
238: throws UnsupportedQueryResultFormatException {
239: TupleQueryResultWriterFactory factory = TupleQueryResultWriterRegistry
240: .getInstance().get(format);
241:
242: if (factory != null) {
243: return factory.getWriter(out);
244: }
245:
246: throw new UnsupportedQueryResultFormatException(
247: "No writer factory available for tuple query result format "
248: + format);
249: }
250:
251: /**
252: * Convenience methods for creating BooleanQueryResultParser objects. This
253: * method uses the registry returned by
254: * {@link BooleanQueryResultParserRegistry#getInstance()} to get a factory
255: * for the specified format and uses this factory to create the appropriate
256: * parser.
257: *
258: * @throws UnsupportedQueryResultFormatException
259: * If no parser is available for the specified boolean query result
260: * format.
261: */
262: public static BooleanQueryResultParser createParser(
263: BooleanQueryResultFormat format)
264: throws UnsupportedQueryResultFormatException {
265: BooleanQueryResultParserFactory factory = BooleanQueryResultParserRegistry
266: .getInstance().get(format);
267:
268: if (factory != null) {
269: return factory.getParser();
270: }
271:
272: throw new UnsupportedQueryResultFormatException(
273: "No parser factory available for boolean query result format "
274: + format);
275: }
276:
277: /**
278: * Convenience methods for creating BooleanQueryResultWriter objects. This
279: * method uses the registry returned by
280: * {@link BooleanQueryResultWriterRegistry#getInstance()} to get a factory
281: * for the specified format and uses this factory to create the appropriate
282: * writer.
283: *
284: * @throws UnsupportedQueryResultFormatException
285: * If no writer is available for the specified boolean query result
286: * format.
287: */
288: public static BooleanQueryResultWriter createWriter(
289: BooleanQueryResultFormat format, OutputStream out)
290: throws UnsupportedQueryResultFormatException {
291: BooleanQueryResultWriterFactory factory = BooleanQueryResultWriterRegistry
292: .getInstance().get(format);
293:
294: if (factory != null) {
295: return factory.getWriter(out);
296: }
297:
298: throw new UnsupportedQueryResultFormatException(
299: "No writer factory available for boolean query result format "
300: + format);
301: }
302:
303: /**
304: * Parses a query result document, reporting the parsed solutions to the
305: * supplied TupleQueryResultHandler.
306: *
307: * @param in
308: * An InputStream to read the query result document from.
309: * @param format
310: * The query result format of the document to parse. Supported formats
311: * are {@link TupleQueryResultFormat#SPARQL} and
312: * {@link TupleQueryResultFormat#BINARY}.
313: * @param handler
314: * The TupleQueryResultHandler to report the parse results to.
315: * @throws IOException
316: * If an I/O error occured while reading the query result document
317: * from the stream.
318: * @throws TupleQueryResultHandlerException
319: * If such an exception is thrown by the supplied
320: * TupleQueryResultHandler.
321: * @throws UnsupportedQueryResultFormatException
322: * @throws IllegalArgumentException
323: * If an unsupported query result file format was specified.
324: */
325: public static void parse(InputStream in,
326: TupleQueryResultFormat format,
327: TupleQueryResultHandler handler, ValueFactory valueFactory)
328: throws IOException, QueryResultParseException,
329: TupleQueryResultHandlerException,
330: UnsupportedQueryResultFormatException {
331: TupleQueryResultParser parser = createParser(format);
332: parser.setValueFactory(valueFactory);
333: parser.setTupleQueryResultHandler(handler);
334: parser.parse(in);
335: }
336:
337: /**
338: * Parses a query result document and returns it as a TupleQueryResult
339: * object.
340: *
341: * @param in
342: * An InputStream to read the query result document from.
343: * @param format
344: * The query result format of the document to parse. Supported formats
345: * are {@link TupleQueryResultFormat#SPARQL} and
346: * {@link TupleQueryResultFormat#BINARY}.
347: * @throws IOException
348: * If an I/O error occured while reading the query result document
349: * from the stream.
350: * @throws TupleQueryResultHandlerException
351: * If such an exception is thrown by the used query result parser.
352: * @throws UnsupportedQueryResultFormatException
353: * @throws IllegalArgumentException
354: * If an unsupported query result file format was specified.
355: */
356: public static TupleQueryResult parse(InputStream in,
357: TupleQueryResultFormat format) throws IOException,
358: QueryResultParseException,
359: TupleQueryResultHandlerException,
360: UnsupportedQueryResultFormatException {
361: TupleQueryResultParser parser = createParser(format);
362:
363: TupleQueryResultBuilder qrBuilder = new TupleQueryResultBuilder();
364: parser.setTupleQueryResultHandler(qrBuilder);
365:
366: parser.parse(in);
367:
368: return qrBuilder.getQueryResult();
369: }
370:
371: /**
372: * Parses a boolean query result document and returns the parsed value.
373: *
374: * @param in
375: * An InputStream to read the query result document from.
376: * @param format
377: * The file format of the document to parse.
378: * @throws IOException
379: * If an I/O error occured while reading the query result document
380: * from the stream.
381: * @throws UnsupportedQueryResultFormatException
382: * If an unsupported query result file format was specified.
383: */
384: public static boolean parse(InputStream in,
385: BooleanQueryResultFormat format) throws IOException,
386: QueryResultParseException,
387: UnsupportedQueryResultFormatException {
388: BooleanQueryResultParser parser = createParser(format);
389: return parser.parse(in);
390: }
391:
392: /**
393: * Writes a query result document in a specific query result format to an
394: * output stream.
395: *
396: * @param tqr
397: * The query result to write.
398: * @param format
399: * The file format of the document to write.
400: * @param out
401: * An OutputStream to write the document to.
402: * @throws IOException
403: * If an I/O error occured while writing the query result document to
404: * the stream.
405: * @throws TupleQueryResultHandlerException
406: * If such an exception is thrown by the used query result writer.
407: * @throws UnsupportedQueryResultFormatException
408: * @throws QueryEvaluationException
409: * If an unsupported query result file format was specified.
410: */
411: public static void write(TupleQueryResult tqr,
412: TupleQueryResultFormat format, OutputStream out)
413: throws IOException, TupleQueryResultHandlerException,
414: UnsupportedQueryResultFormatException,
415: QueryEvaluationException {
416: TupleQueryResultWriter writer = createWriter(format, out);
417: try {
418: QueryResultUtil.report(tqr, writer);
419: } catch (TupleQueryResultHandlerException e) {
420: if (e.getCause() instanceof IOException) {
421: throw (IOException) e.getCause();
422: } else {
423: throw e;
424: }
425: }
426: }
427:
428: /**
429: * Writes a boolean query result document in a specific boolean query result
430: * format to an output stream.
431: *
432: * @param value
433: * The value to write.
434: * @param format
435: * The file format of the document to write.
436: * @param out
437: * An OutputStream to write the document to.
438: * @throws IOException
439: * If an I/O error occured while writing the query result document to
440: * the stream.
441: * @throws UnsupportedQueryResultFormatException
442: * If an unsupported query result file format was specified.
443: */
444: public static void write(boolean value,
445: BooleanQueryResultFormat format, OutputStream out)
446: throws IOException, UnsupportedQueryResultFormatException {
447: BooleanQueryResultWriter writer = createWriter(format, out);
448: writer.write(value);
449: }
450:
451: /**
452: * Writes a graph query result document in a specific RDF format to an output
453: * stream.
454: *
455: * @param gqr
456: * The query result to write.
457: * @param format
458: * The file format of the document to write.
459: * @param out
460: * An OutputStream to write the document to.
461: * @throws IOException
462: * If an I/O error occured while writing the query result document to
463: * the stream.
464: * @throws RDFHandlerException
465: * If such an exception is thrown by the used RDF writer.
466: * @throws QueryEvaluationException
467: * @throws UnsupportedRDFormatException
468: * If an unsupported query result file format was specified.
469: */
470: public static void write(GraphQueryResult gqr, RDFFormat format,
471: OutputStream out) throws IOException, RDFHandlerException,
472: UnsupportedRDFormatException, QueryEvaluationException {
473: RDFWriter writer = Rio.createWriter(format, out);
474: try {
475: QueryResultUtil.report(gqr, writer);
476: } catch (RDFHandlerException e) {
477: if (e.getCause() instanceof IOException) {
478: throw (IOException) e.getCause();
479: } else {
480: throw e;
481: }
482: }
483: }
484: }
|