URL (Groovy JDK enhancements)

Package: java.net

## Class URL

- - ### Methods Summary

    Methods
    Return type | Name and parameters
    --- | ---
    `void` | `eachByte(Closure closure)` Reads the InputStream from this URL, passing each byte to the given closure.
    `void` | `eachByte(int bufferLen, Closure closure)` Reads the InputStream from this URL, passing a byte[] and a number of bytes to the given closure.
    `Object` | `eachLine(Closure closure)` Iterates through the lines read from the URL's associated input stream passing each line to the given 1 or 2 arg closure.
    `Object` | `eachLine(int firstLine, Closure closure)` Iterates through the lines read from the URL's associated input stream passing each line to the given 1 or 2 arg closure.
    `Object` | `eachLine(String charset, Closure closure)` Iterates through the lines read from the URL's associated input stream passing each line to the given 1 or 2 arg closure.
    `Object` | `eachLine(String charset, int firstLine, Closure closure)` Iterates through the lines read from the URL's associated input stream passing each line to the given 1 or 2 arg closure.
    `Writable` | `filterLine(Closure predicate)` Filter lines from a URL using a closure predicate.
    `void` | `filterLine(Writer writer, Closure predicate)` Uses a closure to filter lines from this URL and pass them to the given writer.
    `void` | `filterLine(Writer writer, String charset, Closure predicate)` Uses a closure to filter lines from this URL and pass them to the given writer.
    `Writable` | `filterLine(String charset, Closure predicate)` Filter lines from a URL using a closure predicate.
    `byte[]` | `getBytes()` Read the content of this URL and returns it as a byte[].
    `byte[]` | `getBytes(Map parameters)` Read the content of this URL and returns it as a byte[].
    `String` | `getText()` Read the content of this URL and returns it as a String.
    `String` | `getText(String charset)` Read the data from this URL and return it as a String.
    `String` | `getText(Map parameters)` Read the content of this URL and returns it as a String.
    `String` | `getText(Map parameters, String charset)` Read the data from this URL and return it as a String.
    `BufferedInputStream` | `newInputStream()` Creates a buffered input stream for this URL.
    `BufferedInputStream` | `newInputStream(Map parameters)` Creates a buffered input stream for this URL.
    `BufferedReader` | `newReader()` Creates a buffered reader for this URL.
    `BufferedReader` | `newReader(String charset)` Creates a buffered reader for this URL using the given encoding.
    `BufferedReader` | `newReader(Map parameters)` Creates a buffered reader for this URL.
    `BufferedReader` | `newReader(Map parameters, String charset)` Creates a buffered reader for this URL using the given encoding.
    `List` | `readLines()` Reads the URL contents into a list, with one element for each line.
    `List` | `readLines(String charset)` Reads the URL contents into a list, with one element for each line.
    `Object` | `splitEachLine(String regex, Closure closure)` Iterates through the input stream associated with this URL line by line, splitting each line using the given regex separator.
    `Object` | `splitEachLine(String regex, String charset, Closure closure)` Iterates through the input stream associated with this URL line by line, splitting each line using the given regex separator.
    `Object` | `splitEachLine(Pattern pattern, Closure closure)` Iterates through the input stream associated with this URL line by line, splitting each line using the given regex separator Pattern.
    `Object` | `splitEachLine(Pattern pattern, String charset, Closure closure)` Iterates through the input stream associated with this URL line by line, splitting each line using the given regex separator Pattern.
    `Object` | `withInputStream(Closure closure)` Creates a new InputStream for this URL and passes it into the closure.
    `Object` | `withReader(Closure closure)` Helper method to create a new BufferedReader for a URL and then passes it to the closure.
    `Object` | `withReader(String charset, Closure closure)` Helper method to create a new Reader for a URL and then passes it to the closure.

  - #### Methods inherited from class java.lang.Object

    `addShutdownHook`, `any`, `any`, `asBoolean`, `asType`, `collect`, `collect`, `collect`, `dump`, `each`, `eachMatch`, `eachMatch`, `eachWithIndex`, `every`, `every`, `find`, `find`, `findAll`, `findAll`, `findIndexOf`, `findIndexOf`, `findIndexValues`, `findIndexValues`, `findLastIndexOf`, `findLastIndexOf`, `findResult`, `findResult`, `findResult`, `findResult`, `getAt`, `getMetaClass`, `getMetaPropertyValues`, `getProperties`, `grep`, `grep`, `hasProperty`, `identity`, `inject`, `inject`, `inspect`, `invokeMethod`, `is`, `isCase`, `isNotCase`, `iterator`, `metaClass`, `print`, `print`, `printf`, `printf`, `println`, `println`, `println`, `putAt`, `respondsTo`, `respondsTo`, `setMetaClass`, `split`, `sprintf`, `sprintf`, `stream`, `tap`, `toString`, `use`, `use`, `use`, `with`, `with`, `withCloseable`, `withMethodClosure`, `withStream`, `withTraits`

- - ### Methods Detail

    - #### public void eachByte(Closure closure)

      Reads the InputStream from this URL, passing each byte to the given closure. The URL stream will be closed before this method returns.

      Parameters:
        `closure` - closure to apply to each byte
      Since:
        1.0
      See Also:
        IOGroovyMethods#eachByte(java.io.InputStream, groovy.lang.Closure)

    - #### public void eachByte(int bufferLen, Closure closure)

      Reads the InputStream from this URL, passing a byte[] and a number of bytes to the given closure. The URL stream will be closed before this method returns.

      Parameters:
        `bufferLen` - the length of the buffer to use.
        `closure` - a 2 parameter closure which is passed the byte[] and a number of bytes successfully read.
      Since:
        1.8
      See Also:
        IOGroovyMethods#eachByte(java.io.InputStream, int, groovy.lang.Closure)

    - #### public Object eachLine(Closure closure)

      Iterates through the lines read from the URL's associated input stream passing each line to the given 1 or 2 arg closure. The stream is closed before this method returns.

      Parameters:
        `closure` - a closure to apply on each line (arg 1 is line, optional arg 2 is line number starting at line 1)
      Returns:
        the last value returned by the closure
      Since:
        1.5.6
      See Also:
        URL#eachLine(int, groovy.lang.Closure)

    - #### public Object eachLine(int firstLine, Closure closure)

      Iterates through the lines read from the URL's associated input stream passing each line to the given 1 or 2 arg closure. The stream is closed before this method returns.

      Parameters:
        `firstLine` - the line number value used for the first line (default is 1, set to 0 to start counting from 0)
        `closure` - a closure to apply on each line (arg 1 is line, optional arg 2 is line number)
      Returns:
        the last value returned by the closure
      Since:
        1.5.7
      See Also:
        IOGroovyMethods#eachLine(java.io.InputStream, int, groovy.lang.Closure)

    - #### public Object eachLine(String charset, Closure closure)

      Iterates through the lines read from the URL's associated input stream passing each line to the given 1 or 2 arg closure. The stream is closed before this method returns.

      Parameters:
        `charset` - opens the stream with a specified charset
        `closure` - a closure to apply on each line (arg 1 is line, optional arg 2 is line number starting at line 1)
      Returns:
        the last value returned by the closure
      Since:
        1.5.6
      See Also:
        URL#eachLine(java.lang.String, int, groovy.lang.Closure)

    - #### public Object eachLine(String charset, int firstLine, Closure closure)

      Iterates through the lines read from the URL's associated input stream passing each line to the given 1 or 2 arg closure. The stream is closed before this method returns.

      Parameters:
        `charset` - opens the stream with a specified charset
        `firstLine` - the line number value used for the first line (default is 1, set to 0 to start counting from 0)
        `closure` - a closure to apply on each line (arg 1 is line, optional arg 2 is line number)
      Returns:
        the last value returned by the closure
      Since:
        1.5.7
      See Also:
        IOGroovyMethods#eachLine(java.io.Reader, int, groovy.lang.Closure)

    - #### public Writable filterLine(Closure predicate)

      Filter lines from a URL using a closure predicate. The closure will be passed each line as a String, and it should return `true` if the line should be passed to the writer.

      Parameters:
        `predicate` - a closure which returns boolean and takes a line
      Returns:
        a writable which writes out the filtered lines
      Since:
        1.6.8
      See Also:
        IOGroovyMethods#filterLine(java.io.Reader, groovy.lang.Closure)

    - #### public void filterLine(Writer writer, Closure predicate)

      Uses a closure to filter lines from this URL and pass them to the given writer. The closure will be passed each line as a String, and it should return `true` if the line should be passed to the writer.

      Parameters:
        `writer` - a writer to write output to
        `predicate` - a closure which returns true if a line should be accepted
      Since:
        1.6.8
      See Also:
        IOGroovyMethods#filterLine(java.io.Reader, java.io.Writer, groovy.lang.Closure)

    - #### public void filterLine(Writer writer, String charset, Closure predicate)

      Uses a closure to filter lines from this URL and pass them to the given writer. The closure will be passed each line as a String, and it should return `true` if the line should be passed to the writer.

      Parameters:
        `writer` - a writer to write output to
        `charset` - opens the URL with a specified charset
        `predicate` - a closure which returns true if a line should be accepted
      Since:
        1.6.8
      See Also:
        IOGroovyMethods#filterLine(java.io.Reader, java.io.Writer, groovy.lang.Closure)

    - #### public Writable filterLine(String charset, Closure predicate)

      Filter lines from a URL using a closure predicate. The closure will be passed each line as a String, and it should return `true` if the line should be passed to the writer.

      Parameters:
        `charset` - opens the URL with a specified charset
        `predicate` - a closure which returns boolean and takes a line
      Returns:
        a writable which writes out the filtered lines
      Since:
        1.6.8
      See Also:
        IOGroovyMethods#filterLine(java.io.Reader, groovy.lang.Closure)

    - #### public byte[] getBytes()

      Read the content of this URL and returns it as a byte[].

      Returns:
        the byte[] from that URL
      Since:
        1.7.1

    - #### public byte[] getBytes(Map parameters)

      Read the content of this URL and returns it as a byte[]. The default connection parameters can be modified by adding keys to the parameters map:

      - connectTimeout : the connection timeout
      - readTimeout : the read timeout
      - useCaches : set the use cache property for the URL connection
      - allowUserInteraction : set the user interaction flag for the URL connection
      - requestProperties : a map of properties to be passed to the URL connection
      Parameters:
        `parameters` - connection parameters
      Returns:
        the byte[] from that URL
      Since:
        2.4.4

    - #### public String getText()

      Read the content of this URL and returns it as a String.

      Returns:
        the text from that URL
      Since:
        1.0

    - #### public String getText(String charset)

      Read the data from this URL and return it as a String. The connection stream is closed before this method returns.

      Parameters:
        `charset` - opens the stream with a specified charset
      Returns:
        the text from that URL
      Since:
        1.0
      See Also:
        URLConnection#getInputStream()

    - #### public String getText(Map parameters)

      Read the content of this URL and returns it as a String. The default connection parameters can be modified by adding keys to the parameters map:

      - connectTimeout : the connection timeout
      - readTimeout : the read timeout
      - useCaches : set the use cache property for the URL connection
      - allowUserInteraction : set the user interaction flag for the URL connection
      - requestProperties : a map of properties to be passed to the URL connection
      Parameters:
        `parameters` - connection parameters
      Returns:
        the text from that URL
      Since:
        1.8.1

    - #### public String getText(Map parameters, String charset)

      Read the data from this URL and return it as a String. The connection stream is closed before this method returns.

      Parameters:
        `parameters` - connection parameters
        `charset` - opens the stream with a specified charset
      Returns:
        the text from that URL
      Since:
        1.8.1
      See Also:
        URLConnection#getInputStream()

    - #### public BufferedInputStream newInputStream()

      Creates a buffered input stream for this URL.

      Returns:
        a BufferedInputStream for the URL
      Since:
        1.5.2

    - #### public BufferedInputStream newInputStream(Map parameters)

      Creates a buffered input stream for this URL. The default connection parameters can be modified by adding keys to the parameters map:

      - connectTimeout : the connection timeout
      - readTimeout : the read timeout
      - useCaches : set the use cache property for the URL connection
      - allowUserInteraction : set the user interaction flag for the URL connection
      - requestProperties : a map of properties to be passed to the URL connection
      Parameters:
        `parameters` - connection parameters
      Returns:
        a BufferedInputStream for the URL
      Since:
        1.8.1

    - #### public BufferedReader newReader()

      Creates a buffered reader for this URL.

      Returns:
        a BufferedReader for the URL
      Since:
        1.5.5

    - #### public BufferedReader newReader(String charset)

      Creates a buffered reader for this URL using the given encoding.

      Parameters:
        `charset` - opens the stream with a specified charset
      Returns:
        a BufferedReader for the URL
      Since:
        1.5.5

    - #### public BufferedReader newReader(Map parameters)

      Creates a buffered reader for this URL. The default connection parameters can be modified by adding keys to the parameters map:

      - connectTimeout : the connection timeout
      - readTimeout : the read timeout
      - useCaches : set the use cache property for the URL connection
      - allowUserInteraction : set the user interaction flag for the URL connection
      - requestProperties : a map of properties to be passed to the URL connection
      Parameters:
        `parameters` - connection parameters
      Returns:
        a BufferedReader for the URL
      Since:
        1.8.1

    - #### public BufferedReader newReader(Map parameters, String charset)

      Creates a buffered reader for this URL using the given encoding.

      Parameters:
        `parameters` - connection parameters
        `charset` - opens the stream with a specified charset
      Returns:
        a BufferedReader for the URL
      Since:
        1.8.1

    - #### public List readLines()

      Reads the URL contents into a list, with one element for each line.

      Returns:
        a List of lines
      Since:
        1.6.8
      See Also:
        IOGroovyMethods#readLines(java.io.Reader)

    - #### public List readLines(String charset)

      Reads the URL contents into a list, with one element for each line.

      Parameters:
        `charset` - opens the URL with a specified charset
      Returns:
        a List of lines
      Since:
        1.6.8
      See Also:
        IOGroovyMethods#readLines(java.io.Reader)

    - #### public Object splitEachLine(String regex, Closure closure)

      Iterates through the input stream associated with this URL line by line, splitting each line using the given regex separator. For each line, the given closure is called with a single parameter being the list of strings computed by splitting the line around matches of the given regular expression. Finally the resources used for processing the URL are closed.

      Parameters:
        `regex` - the delimiting regular expression
        `closure` - a closure
      Returns:
        the last value returned by the closure
      Since:
        1.6.8
      See Also:
        IOGroovyMethods#splitEachLine(java.io.Reader, java.lang.String, groovy.lang.Closure)

    - #### public Object splitEachLine(String regex, String charset, Closure closure)

      Iterates through the input stream associated with this URL line by line, splitting each line using the given regex separator. For each line, the given closure is called with a single parameter being the list of strings computed by splitting the line around matches of the given regular expression. Finally the resources used for processing the URL are closed.

      Parameters:
        `regex` - the delimiting regular expression
        `charset` - opens the file with a specified charset
        `closure` - a closure
      Returns:
        the last value returned by the closure
      Since:
        1.6.8
      See Also:
        IOGroovyMethods#splitEachLine(java.io.Reader, java.lang.String, groovy.lang.Closure)

    - #### public Object splitEachLine(Pattern pattern, Closure closure)

      Iterates through the input stream associated with this URL line by line, splitting each line using the given regex separator Pattern. For each line, the given closure is called with a single parameter being the list of strings computed by splitting the line around matches of the given regular expression. Finally the resources used for processing the URL are closed.

      Parameters:
        `pattern` - the regular expression Pattern for the delimiter
        `closure` - a closure
      Returns:
        the last value returned by the closure
      Since:
        1.6.8
      See Also:
        IOGroovyMethods#splitEachLine(java.io.Reader, java.util.regex.Pattern, groovy.lang.Closure)

    - #### public Object splitEachLine(Pattern pattern, String charset, Closure closure)

      Iterates through the input stream associated with this URL line by line, splitting each line using the given regex separator Pattern. For each line, the given closure is called with a single parameter being the list of strings computed by splitting the line around matches of the given regular expression. Finally the resources used for processing the URL are closed.

      Parameters:
        `pattern` - the regular expression Pattern for the delimiter
        `charset` - opens the file with a specified charset
        `closure` - a closure
      Returns:
        the last value returned by the closure
      Since:
        1.6.8
      See Also:
        IOGroovyMethods#splitEachLine(java.io.Reader, java.util.regex.Pattern, groovy.lang.Closure)

    - #### public Object withInputStream(Closure closure)

      Creates a new InputStream for this URL and passes it into the closure. This method ensures the stream is closed after the closure returns.

      Parameters:
        `closure` - a closure
      Returns:
        the value returned by the closure
      Since:
        1.5.2
      See Also:
        IOGroovyMethods#withStream(java.io.InputStream, groovy.lang.Closure)

    - #### public Object withReader(Closure closure)

      Helper method to create a new BufferedReader for a URL and then passes it to the closure. The reader is closed after the closure returns.

      Parameters:
        `closure` - the closure to invoke with the reader
      Returns:
        the value returned by the closure
      Since:
        1.5.2

    - #### public Object withReader(String charset, Closure closure)

      Helper method to create a new Reader for a URL and then passes it to the closure. The reader is closed after the closure returns.

      Parameters:
        `charset` - the charset used
        `closure` - the closure to invoke with the reader
      Returns:
        the value returned by the closure
      Since:
        1.5.6