001/*
002 * The MIT License
003 * Copyright (c) 2012 Microsoft Corporation
004 *
005 * Permission is hereby granted, free of charge, to any person obtaining a copy
006 * of this software and associated documentation files (the "Software"), to deal
007 * in the Software without restriction, including without limitation the rights
008 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
009 * copies of the Software, and to permit persons to whom the Software is
010 * furnished to do so, subject to the following conditions:
011 *
012 * The above copyright notice and this permission notice shall be included in
013 * all copies or substantial portions of the Software.
014 *
015 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
016 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
017 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
018 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
019 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
020 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
021 * THE SOFTWARE.
022 */
023
024package microsoft.exchange.webservices.data.core;
025
026import javax.xml.stream.XMLEventReader;
027import javax.xml.stream.XMLInputFactory;
028import javax.xml.stream.XMLStreamException;
029
030import java.io.BufferedReader;
031import java.io.InputStream;
032import java.io.InputStreamReader;
033
034/**
035 * Represents an xml reader used by the ExchangeService to parse multi-response streams,
036 * such as GetStreamingEvents.
037 * <p>
038 * Necessary because the basic EwsServiceXmlReader does not
039 * use normalization (see E14:60369), and in order to turn normalization off, it is
040 * necessary to use an XmlTextReader, which does not allow the ConformanceLevel.Auto that
041 * a multi-response stream requires.
042 * If ever there comes a time we need to deal with multi-response streams with user-generated
043 * content, we will need to tackle that parsing problem separately.
044 * </p>
045 */
046public class EwsServiceMultiResponseXmlReader extends EwsServiceXmlReader {
047
048  /**
049   * Initializes a new instance of the
050   * EwsServiceMultiResponseXmlReader class.
051   *
052   * @param stream  The stream.
053   * @param service The service.
054   * @throws Exception
055   */
056  private EwsServiceMultiResponseXmlReader(InputStream stream,
057      ExchangeService service) throws Exception {
058    super(stream, service);
059  }
060
061  /**
062   * Creates a new instance of the EwsServiceMultiResponseXmlReader class.
063   *
064   * @param stream the stream
065   * @param service the service
066   * @return an instance of EwsServiceMultiResponseXmlReader wrapped around the input stream
067   * @throws Exception on error
068   */
069  public static EwsServiceMultiResponseXmlReader create(InputStream stream, ExchangeService service) throws Exception {
070    return new EwsServiceMultiResponseXmlReader(stream, service);
071  }
072
073  /**
074   * Creates the XML reader.
075   *
076   * @param stream The stream
077   * @return an XML reader to use
078   * @throws XMLStreamException the XML stream exception
079   */
080  private static XMLEventReader createXmlReader(InputStream stream)
081      throws XMLStreamException {
082
083    // E14:240522 The ProhibitDtd property is used to indicate whether XmlReader should process DTDs or not. By default,
084    // it will do so. EWS doesn't use DTD references so we want to turn this off. Also, the XmlResolver property is
085    // set to an instance of XmlUrlResolver by default. We don't want XmlTextReader to try to resolve this DTD reference
086    // so we disable the XmlResolver as well.
087    XMLInputFactory inputFactory = XMLInputFactory.newInstance();
088    InputStreamReader isr = new InputStreamReader(stream);
089    BufferedReader in = new BufferedReader(isr);
090    return inputFactory.createXMLEventReader(in);
091  }
092
093
094  /**
095   * Initializes the XML reader.
096   *
097   * @param stream The stream. An XML reader to use.
098   * @throws Exception on error
099   */
100  @Override
101  protected XMLEventReader initializeXmlReader(InputStream stream)
102      throws Exception {
103    return createXmlReader(stream);
104  }
105
106}