Package org.apache.sling.scripting.javascript.io

Class EspReader

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, java.lang.Readable
    public class EspReader
extends java.io.FilterReader
    The EspReader is a FilterReader which takes JSP like input and produces plain ECMA script output. The filtering modifications done on the input comprise the following :
    • Template text (HTML) is wrapped by out.write(). At most one line of text is wrapped into a single write() call. Double quote characters in the template text (e.g. for HTML tag attribute values) are escaped.
    • ECMA code is written to the output as is.
    • ECMA slash star (/*) comments are also written as is.
    • ECMA slash slash (//) comments are written as is.
    • JSP style template comments (<%-- -->) are also removed from the stream. Lineendings (LFs and CRLFs) are written, though.
    • HTML comments (<!-- -->) are not treated specially. Rather they are handled as plain template text written to the output wrapped in out.write(). The consequence of this behaviour is, that as in JSP ECMA expressions may be included within the comments.

    The nice thing about this reader is, that the line numbers of the resulting stream match the line numbers of the matching contents of the input stream. Due to the insertion of write() calls, column numbers will not necessarily match, though. This is especially true if you mix ECMA code tags (<% %>) with template text on the same line.

    For maximum performance it is advisable to not create the EspReader with a plain FileReader or InputStreamReader but rather with a BufferedReader based on one of the simpler Readers. The reasons for this is, that we call the base reader character by character. This in turn is not too performing if the base reader does not buffer its input.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String DEFAULT_OUT_INIT_STATEMENT
      Javascript statement that sets the "out" variable that's used to output data.

      • Fields inherited from class java.io.FilterReader

        in

      • Fields inherited from class java.io.Reader

        lock

    • Constructor Summary

      Constructors 
      Constructor Description
      EspReader​(java.io.Reader baseReader)
      Create an EspReader on top of the given baseReader.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Close the EspReader.
      void mark​(int readAheadLimit)
      Mark the present position in the stream.
      boolean markSupported()
      Tell whether this stream supports the mark() operation, which it does not.
      int read()
      Return the next filtered character.
      int read​(char[] cbuf)
      Fill the given buffer with filtered or injected characters.
      int read​(char[] cbuf, int off, int len)
      Fill the buffer from the offset with the number of characters given.
      boolean ready()
      Check whether we may block at the next read() operation.
      void reset()
      Reset the stream.
      void setOutInitStatement​(java.lang.String statement)
      Set the code fragment used to initialize the "out" variable
      long skip​(long n)
      Skip the number of filtered characters.

      • Methods inherited from class java.io.Reader

        nullReader, read, transferTo

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • DEFAULT_OUT_INIT_STATEMENT

        public static final java.lang.String DEFAULT_OUT_INIT_STATEMENT
        Javascript statement that sets the "out" variable that's used to output data. Automatically inserted by the reader in code, where needed.
        See Also:
        Constant Field Values

    • Constructor Detail

      • EspReader

        public EspReader​(java.io.Reader baseReader)
        Create an EspReader on top of the given baseReader. The constructor wraps the input reader with a PushbackReader, so that input stream modifications may be handled transparently by our doRead() method.
        Parameters:
        baseReader - the wrapped reader

    • Method Detail

      • setOutInitStatement

        public void setOutInitStatement​(java.lang.String statement)
        Set the code fragment used to initialize the "out" variable
        Parameters:
        statement - the statement used for initialization

      • ready

        public boolean ready()
              throws java.io.IOException
        Check whether we may block at the next read() operation. We may be ready if and only if our input reader is ready. But this does not guarantee that we won't block, as due to filtering there may be more than one character needed from the input to return one.
        Overrides:
        ready in class java.io.FilterReader
        Returns:
        true if a character is available on the PushbackReader.
        Throws:
        java.io.IOException - if the reader is not open

      • read

        public int read()
         throws java.io.IOException
        Return the next filtered character. This need not be the next character of the input stream. It may be a character from the input reader, after having skipped filtered characters or it may be a character injected due to translation of template text to ECMA code.
        Overrides:
        read in class java.io.FilterReader
        Returns:
        the next character after filtering or -1 at the end of the input reader
        Throws:
        java.io.IOException - if the reader is not open

      • read

        public int read​(char[] cbuf)
         throws java.io.IOException
        Fill the given buffer with filtered or injected characters. This need not be the next characters of the input stream. It may be characters from the input reader, after having skipped filtered characters or it may be a characters injected due to translation of template text to ECMA code. This method is exactly the same as read(cbuf, 0, cbuf.length).
        Overrides:
        read in class java.io.Reader
        Parameters:
        cbuf - The character buffer to fill with (filtered) characters
        Returns:
        the number of characters filled in the buffer or -1 at the end of the input reader.
        Throws:
        java.io.IOException - if the reader is not open

      • read

        public int read​(char[] cbuf,
                int off,
                int len)
         throws java.io.IOException
        Fill the buffer from the offset with the number of characters given. This need not be the next characters of the input stream. It may be characters from the input reader, after having skipped filtered characters or it may be a characters injected due to translation of template text to ECMA code.
        Overrides:
        read in class java.io.FilterReader
        Parameters:
        cbuf - The character buffer to fill with (filtered) characters
        off - Offset from where to start in the buffer
        len - The number of characters to fill into the buffer
        Returns:
        the number of characters filled in the buffer or -1 at the end of the input reader.
        Throws:
        java.io.IOException - if the reader is not open
        java.lang.IndexOutOfBoundsException - if len is negative, off is negative or higher than the buffer length or off+len is negative or beyond the buffer size.

      • skip

        public long skip​(long n)
          throws java.io.IOException
        Skip the number of filtered characters. The skip method is the same as calling read() repeatedly for the given number of characters and throwing away the result. If the end of input reader is reached before having skipped the number of characters, the method returns the number characters skipped so far.
        Overrides:
        skip in class java.io.FilterReader
        Parameters:
        n - the number of (filtered) characters to skip
        Returns:
        the number of (filtered) characters actually skipped
        Throws:
        java.lang.IllegalArgumentException - if n is negative
        java.io.IOException - if the reading the characters throws

      • close

        public void close()
           throws java.io.IOException
        Close the EspReader.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class java.io.FilterReader
        Throws:
        java.io.IOException

      • mark

        public void mark​(int readAheadLimit)
          throws java.io.IOException
        Mark the present position in the stream. The mark for class EspReader always throws an throwable.
        Overrides:
        mark in class java.io.FilterReader
        Parameters:
        readAheadLimit - The number of characters to read ahead
        Throws:
        java.io.IOException - Always, since mark is not supported

      • markSupported

        public boolean markSupported()
        Tell whether this stream supports the mark() operation, which it does not.
        Overrides:
        markSupported in class java.io.FilterReader
        Returns:
        false Always, since mark is not supported

      • reset

        public void reset()
           throws java.io.IOException
        Reset the stream. The reset method of EspReader always throws an throwable.
        Overrides:
        reset in class java.io.FilterReader
        Throws:
        java.io.IOException - Always, since reset is not supported