com.atlassian.jira.util
Class XmlReader

java.lang.Object
  extended by java.io.Reader
      extended by com.atlassian.jira.util.XmlReader
All Implemented Interfaces:
java.io.Closeable, java.lang.Readable

public final class XmlReader
extends java.io.Reader

This handles several XML-related tasks that normal java.io Readers don't support, inluding use of IETF standard encoding names and automatic detection of most XML encodings. The former is needed for interoperability; the latter is needed to conform with the XML spec. This class also optimizes reading some common encodings by providing low-overhead unsynchronized Reader support.

Note that the autodetection facility should be used only on data streams which have an unknown character encoding. For example, it should never be used on MIME text/xml entities.

Note that XML processors are only required to support UTF-8 and UTF-16 character encodings. Autodetection permits the underlying Java implementation to provide support for many other encodings, such as US-ASCII, ISO-8859-5, Shift_JIS, EUC-JP, and ISO-2022-JP.

Version:
$Revision: 1.3 $
Author:
David Brownell

Field Summary
 
Fields inherited from class java.io.Reader
lock
 
Method Summary
 void close()
          Closes the reader.
static XmlReader createReader(java.io.InputStream in)
          Constructs the reader from an input stream, autodetecting the encoding to use according to the heuristic specified in the XML 1.0 recommendation.
static java.io.Reader createReader(java.io.InputStream in, java.lang.String encoding)
          Creates a reader supporting the given encoding, mapping from standard encoding names to ones that understood by Java where necessary.
 java.lang.String getEncoding()
          Returns the standard name of the encoding in use
 java.io.InputStream getInputStream()
           
 void mark(int value)
          Sets a mark allowing a limited number of characters to be "peeked", by reading and then resetting.
 boolean markSupported()
          Returns true iff the reader supports mark/reset.
 int read()
          Reads a single character.
 int read(char[] buf, int off, int len)
          Reads the number of characters read into the buffer, or -1 on EOF.
 boolean ready()
          Returns true iff input characters are known to be ready.
 void reset()
          Resets the current position to the last marked position.
 long skip(long value)
          Skips a specified number of characters.
 
Methods inherited from class java.io.Reader
read, read
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

createReader

public static XmlReader createReader(java.io.InputStream in)
                              throws java.io.IOException
Constructs the reader from an input stream, autodetecting the encoding to use according to the heuristic specified in the XML 1.0 recommendation.

Parameters:
in - the input stream from which the reader is constructed
Throws:
java.io.IOException - on error, such as unrecognized encoding

createReader

public static java.io.Reader createReader(java.io.InputStream in,
                                          java.lang.String encoding)
                                   throws java.io.IOException
Creates a reader supporting the given encoding, mapping from standard encoding names to ones that understood by Java where necessary.

Parameters:
in - the input stream from which the reader is constructed
encoding - the IETF standard name of the encoding to use; if null, autodetection is used.
Throws:
java.io.IOException - on error, including unrecognized encoding

getEncoding

public java.lang.String getEncoding()
Returns the standard name of the encoding in use


getInputStream

public java.io.InputStream getInputStream()

read

public int read(char[] buf,
                int off,
                int len)
         throws java.io.IOException
Reads the number of characters read into the buffer, or -1 on EOF.

Specified by:
read in class java.io.Reader
Throws:
java.io.IOException

read

public int read()
         throws java.io.IOException
Reads a single character.

Overrides:
read in class java.io.Reader
Throws:
java.io.IOException

markSupported

public boolean markSupported()
Returns true iff the reader supports mark/reset.

Overrides:
markSupported in class java.io.Reader

mark

public void mark(int value)
          throws java.io.IOException
Sets a mark allowing a limited number of characters to be "peeked", by reading and then resetting.

Overrides:
mark in class java.io.Reader
Parameters:
value - how many characters may be "peeked".
Throws:
java.io.IOException

reset

public void reset()
           throws java.io.IOException
Resets the current position to the last marked position.

Overrides:
reset in class java.io.Reader
Throws:
java.io.IOException

skip

public long skip(long value)
          throws java.io.IOException
Skips a specified number of characters.

Overrides:
skip in class java.io.Reader
Throws:
java.io.IOException

ready

public boolean ready()
              throws java.io.IOException
Returns true iff input characters are known to be ready.

Overrides:
ready in class java.io.Reader
Throws:
java.io.IOException

close

public void close()
           throws java.io.IOException
Closes the reader.

Specified by:
close in interface java.io.Closeable
Specified by:
close in class java.io.Reader
Throws:
java.io.IOException


Copyright © 2002-2010 Atlassian. All Rights Reserved.