PageRenderTime 46ms CodeModel.GetById 22ms RepoModel.GetById 0ms app.codeStats 0ms

/WorldWind/src/main/java/gov/nasa/worldwind/ogc/ows/OWSExceptionReport.java

http://geoforge.googlecode.com/
Java | 339 lines | 153 code | 32 blank | 154 comment | 27 complexity | 1862b6f942dc68e3ad6d0034850c4ed0 MD5 | raw file
Possible License(s): LGPL-3.0, GPL-2.0, GPL-3.0, LGPL-2.1, LGPL-2.0
  1. /*
  2. * Copyright (C) 2011 United States Government as represented by the Administrator of the
  3. * National Aeronautics and Space Administration.
  4. * All Rights Reserved.
  5. */
  6. package gov.nasa.worldwind.ogc.ows;
  7. import gov.nasa.worldwind.exception.WWRuntimeException;
  8. import gov.nasa.worldwind.util.*;
  9. import gov.nasa.worldwind.util.xml.*;
  10. import javax.xml.namespace.QName;
  11. import javax.xml.stream.*;
  12. import javax.xml.stream.events.XMLEvent;
  13. import java.util.*;
  14. import java.util.logging.Level;
  15. /**
  16. * Parses an OGC Web Service Common (OWS) ExceptionReport element and provides access to its contents. See
  17. * http://schemas.opengis.net/ows/2.0/owsExceptionReport.xsd.
  18. * <p/>
  19. * Service exception reports are generated by an OGC Web Service (OWS) upon receiving an invalid client request and upon
  20. * detecting an exceptional condition. In either case, the web service responds to the client request with an exception
  21. * report XML document. Exception reports typically contain one or more independent exceptions indicating an independent
  22. * error.
  23. * <p/>
  24. * <code>OWSExceptionReport</code> can parse an OGC exception report XML document and hold the parsed information, or
  25. * export an OGC exception report XML document from its current state. To parse an exception report XML document, create
  26. * a new <code>OWSExceptionReport</code> from a document source and parse its contents by calling <code>{@link
  27. * #OWSExceptionReport(Object)}</code> then <code>{@link #parse(Object...)}</code> on the new
  28. * <code>OWSExceptionReport</code>. To export an exception report's current state to an XML document, call <code>{@link
  29. * #export(Object)}</code>.
  30. *
  31. * @author dcollins
  32. * @version $Id: OWSExceptionReport.java 1 2011-07-16 23:22:47Z dcollins $
  33. */
  34. public class OWSExceptionReport extends AbstractXMLEventParser
  35. {
  36. /**
  37. * Indicates the exception report's list of web service exceptions. Each exception indicates an independent error.
  38. * Initially assigned to a new <code>ArrayList</code>.
  39. */
  40. protected List<OWSException> exceptions = new ArrayList<OWSException>();
  41. /**
  42. * The event reader used to parse the document's XML. This is <code>null<code> if the exception report is not
  43. * created from an XML document source.
  44. */
  45. protected XMLEventReader eventReader;
  46. /**
  47. * The parser context for the document. This is <code>null<code> if the exception report is not created from an XML
  48. * document source.
  49. */
  50. protected XMLEventParserContext parserContext;
  51. /** Creates a new <code>OWSExceptionReport</code> with an empty list of exceptions and no version. */
  52. public OWSExceptionReport()
  53. {
  54. super(OWSConstants.OWS_1dot1_NAMESPACE);
  55. }
  56. /**
  57. * Creates a new <code>OWSExceptionReport</code> from the specified XML document source. The new
  58. * <code>OWSExceptionReport</code> is ready to parse the specified document source. The caller must initiate parsing
  59. * by calling <code>{@link #parse(Object...)}</code>.
  60. *
  61. * @param docSource the XML source. May be a filename, file, stream or other type allowed by <code>{@link
  62. * WWXML#openEventReader(Object)}</code>.
  63. *
  64. * @throws IllegalArgumentException if <code>docSource</code> is <code>null</code>.
  65. * @throws WWRuntimeException if the XML source cannot be opened.
  66. * @see #parse(Object...)
  67. */
  68. public OWSExceptionReport(Object docSource)
  69. {
  70. super(OWSConstants.OWS_1dot1_NAMESPACE);
  71. if (docSource == null)
  72. {
  73. String message = Logging.getMessage("nullValue.DocumentSourceIsNull");
  74. Logging.logger().severe(message);
  75. throw new IllegalArgumentException(message);
  76. }
  77. this.eventReader = this.createReader(docSource);
  78. if (this.eventReader == null)
  79. throw new WWRuntimeException(Logging.getMessage("XML.UnableToOpenDocument", docSource));
  80. this.initializeParser();
  81. }
  82. /**
  83. * Indicates the version string of the OGC web service that generated this exception report. The version it
  84. * typically formatted as <code>x.y.z</code>, where <code>x, y</code> and <code>z</code> are integers in the range
  85. * 0-99.
  86. *
  87. * @return the version of the OGC web service that generated the report, or <code>null</code> if no version is
  88. * available.
  89. *
  90. * @see #setVersion(String)
  91. */
  92. public String getVersion()
  93. {
  94. return (String) this.getField("version");
  95. }
  96. /**
  97. * Specifies the version string of the OGC web service that generated this exception report. The version should be
  98. * formatted as <code>x.y.z</code>, where <code>x, y</code> and <code>z</code> are integers in the range 0-99.
  99. *
  100. * @param version the version of the OGC web service that generated the report, may be <code>null</code>.
  101. *
  102. * @see #getVersion()
  103. */
  104. public void setVersion(String version)
  105. {
  106. this.setField("version", version);
  107. }
  108. /**
  109. * Indicates this exception report's list of web service exceptions. Each exception indicates an independent error.
  110. *
  111. * @return the report's list of web service exceptions, or <code>null</code> if the report has no exceptions.
  112. *
  113. * @see #setExceptions(java.util.List)
  114. */
  115. public List<OWSException> getExceptions()
  116. {
  117. return this.exceptions;
  118. }
  119. /**
  120. * Specifies this exception report's list of web service exceptions. Each exception indicates an independent error.
  121. *
  122. * @param exceptions a list of exceptions, or <code>null</code> to specify that the report has no exceptions.
  123. *
  124. * @see #getExceptions()
  125. */
  126. public void setExceptions(List<OWSException> exceptions)
  127. {
  128. this.exceptions = exceptions;
  129. }
  130. /**
  131. * Adds the specified <code>exception</code> to this exception report's internal exception list. This does nothing
  132. * if the <code>exception</code> is <code>null</code> or if the internal exception list has been set to
  133. * <code>null</code>.
  134. *
  135. * @param exception the OGC exception to add, may be <code>null</code>.
  136. */
  137. public void addException(OWSException exception)
  138. {
  139. if (this.getExceptions() != null && exception != null)
  140. this.getExceptions().add(exception);
  141. }
  142. /**
  143. * Called from the constructor that takes an XML document source, just before it returns. If overriding this method
  144. * be sure to call <code>super.initialize()</code>.
  145. *
  146. * @see #OWSExceptionReport(Object)
  147. */
  148. protected void initializeParser()
  149. {
  150. this.parserContext = this.createParserContext(this.eventReader);
  151. }
  152. /**
  153. * Creates the exception report's XML event reader. Called from the constructor that takes an XML document source.
  154. *
  155. * @param docSource the document source to create a reader for. The type can be any of those supported by {@link
  156. * gov.nasa.worldwind.util.WWXML#openEventReader(Object)}.
  157. *
  158. * @return a new event reader, or null if the source type cannot be determined.
  159. *
  160. * @see #OWSExceptionReport(Object)
  161. */
  162. protected XMLEventReader createReader(Object docSource)
  163. {
  164. return WWXML.openEventReader(docSource);
  165. }
  166. /**
  167. * Called during <code>{@link #initializeParser()}</code> to create the parser context.
  168. *
  169. * @param reader the reader to associate with the parser context.
  170. *
  171. * @return a new parser context.
  172. */
  173. protected XMLEventParserContext createParserContext(XMLEventReader reader)
  174. {
  175. return new OWSParserContext(reader, this.getNamespaceURI());
  176. }
  177. /**
  178. * Indicates the XML parser context created during <code>{@link #initializeParser()}</code>. Returns
  179. * <code>null</code> if the exception report was not created form an XML document source.
  180. *
  181. * @return the XML parser context, or <code>null</code> the exception report does not have a parser context.
  182. */
  183. protected XMLEventParserContext getParserContext()
  184. {
  185. return this.parserContext;
  186. }
  187. /**
  188. * Starts document parsing. This method initiates parsing of the OGC exception report XML document and returns when
  189. * the full exception report document has been parsed. If this exception report was not created from an XML document
  190. * source, this does nothing and returns <code>null</code>.
  191. *
  192. * @param args optional arguments to pass to parsers of sub-elements.
  193. *
  194. * @return <code>this</code> if parsing is successful, otherwise <code>null</code>.
  195. *
  196. * @throws XMLStreamException if an exception occurs while attempting to read the XML document event stream.
  197. * @see #OWSExceptionReport(Object)
  198. */
  199. public OWSExceptionReport parse(Object... args) throws XMLStreamException
  200. {
  201. XMLEventParserContext ctx = this.getParserContext();
  202. if (ctx == null)
  203. return null;
  204. QName rootElementName = new QName(this.getNamespaceURI(), "ExceptionReport");
  205. for (XMLEvent event = ctx.nextEvent(); ctx.hasNext(); event = ctx.nextEvent())
  206. {
  207. if (event == null)
  208. continue;
  209. if (ctx.isStartElement(event, rootElementName))
  210. {
  211. super.parse(ctx, event, args);
  212. return this;
  213. }
  214. }
  215. return null;
  216. }
  217. /**
  218. * Overridden to detect <code>OWSException</code> instances creating during XML document parsing, and add these
  219. * instances to the exception report's internal exception list.
  220. *
  221. * @param o the parsed object to add.
  222. * @param ctx the XML parser context.
  223. * @param event the XML document event.
  224. * @param args optional arguments specified when document parsing started.
  225. *
  226. * @throws XMLStreamException if an exception occurs while attempting to read the XML document event stream.
  227. */
  228. @Override
  229. protected void doAddEventContent(Object o, XMLEventParserContext ctx, XMLEvent event, Object... args)
  230. throws XMLStreamException
  231. {
  232. if (o instanceof OWSException)
  233. {
  234. this.addException((OWSException) o);
  235. }
  236. else
  237. {
  238. super.doAddEventContent(o, ctx, event, args);
  239. }
  240. }
  241. /**
  242. * Writes this exception report and its exception list to the specified <code>output</code> as an OGC Web Service
  243. * Common (OWS) <code>ExceptionReport</code> XML document.
  244. * <p/>
  245. * The exported element is formatted according to the OGC Web Service Common (OWS) specification, and is compatible
  246. * with OWS version <code>1.0.0</code>, <code>1.1.0</code>, and <code>2.0.0</code>.
  247. *
  248. * @param output the XML output stream. May be a <code>{@link java.io.OutputStream}</code>, a <code>{@link
  249. * java.io.Writer}</code>, or any type allowed by <code>{@link gov.nasa.worldwind.util.WWXML#openStreamWriter(Object)}</code>.
  250. *
  251. * @throws IllegalArgumentException if <code>output</code> is <code>null</code>, or if <code>output</code> is not
  252. * one of the recognized types.
  253. * @throws XMLStreamException if an exception occurs while attempting to export the XML event stream.
  254. */
  255. public void export(Object output) throws XMLStreamException
  256. {
  257. if (output == null)
  258. {
  259. String message = Logging.getMessage("nullValue.OutputIsNull");
  260. Logging.logger().severe(message);
  261. throw new IllegalArgumentException(message);
  262. }
  263. XMLStreamWriter writer;
  264. boolean closeWriterWhenFinished = false;
  265. if (output instanceof XMLStreamWriter)
  266. {
  267. writer = (XMLStreamWriter) output;
  268. }
  269. else
  270. {
  271. writer = WWXML.openStreamWriter(output);
  272. closeWriterWhenFinished = true;
  273. }
  274. if (writer == null)
  275. {
  276. String message = Logging.getMessage("Export.UnsupportedOutputObject", output);
  277. Logging.logger().severe(message);
  278. throw new IllegalArgumentException(message);
  279. }
  280. writer.setDefaultNamespace(this.getNamespaceURI());
  281. writer.writeStartDocument();
  282. writer.writeStartElement("ExceptionReport");
  283. writer.writeDefaultNamespace(this.getNamespaceURI());
  284. if (!WWUtil.isEmpty(this.getVersion()))
  285. writer.writeAttribute("version", this.getVersion());
  286. if (this.getExceptions() != null)
  287. {
  288. for (OWSException ex : this.getExceptions())
  289. {
  290. try
  291. {
  292. if (ex != null)
  293. ex.export(writer);
  294. }
  295. catch (Exception e)
  296. {
  297. Logging.logger().log(Level.WARNING, Logging.getMessage("Export.UnableToExportObject", ex), e);
  298. }
  299. }
  300. }
  301. writer.writeEndElement();
  302. writer.writeEndDocument();
  303. writer.flush();
  304. if (closeWriterWhenFinished)
  305. writer.close();
  306. }
  307. }