Package: java.net

## [Java] Class URL

- java.net.URL

-     public class URL
      extends Object

  GDK enhancements for URL.

  displayName:
    URL
  receiverFqcn:
    java.net.URL

- - ### Methods Summary

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

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `addShutdownHook, any, any, asBoolean, asType, clamp, clamp, 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, inject, inject, inspect, invokeMethod, is, isCase, isNotCase, iterator, metaClass, print, print, printf, printf, println, println, println, putAt, respondsTo, respondsTo, setMetaClass, sleep, sleep, split, sprintf, sprintf, stream, takeIf, tap, toString, use, use, use, with, with, withCloseable, withCloseable, withMethodClosure, withStream, withStream, withTraits`

- - ### Method 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.

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

    - #### 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.

      throws:
        IOException if an IOException occurs.
      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.
      See Also:
        IOGroovyMethods#eachByte(java.io.InputStream, int, groovy.lang.Closure)
      Since:
        1.8

    - #### <T> public T eachLine(Closure<T> 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.

      throws:
        IOException if an IOException occurs.
      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
      See Also:
        eachLine(java.net.URL, int, groovy.lang.Closure)
      Since:
        1.5.6

    - #### <T> public T eachLine(int firstLine, Closure<T> 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.

      throws:
        IOException if an IOException occurs.
      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
      See Also:
        IOGroovyMethods#eachLine(java.io.InputStream, int, groovy.lang.Closure)
      Since:
        1.5.7

    - #### <T> public T eachLine(String charset, Closure<T> 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.

      throws:
        IOException if an IOException occurs.
      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
      See Also:
        eachLine(java.net.URL, java.lang.String, int, groovy.lang.Closure)
      Since:
        1.5.6

    - #### <T> public T eachLine(String charset, int firstLine, Closure<T> 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.

      throws:
        IOException if an IOException occurs.
      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
      See Also:
        IOGroovyMethods#eachLine(java.io.Reader, int, groovy.lang.Closure)
      Since:
        1.5.7

    - #### 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.

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

    - #### 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.

      throws:
        IOException if an IO exception occurs
      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
      See Also:
        IOGroovyMethods#filterLine(java.io.Reader, groovy.lang.Closure)
      Since:
        1.6.8

    - #### 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.

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

    - #### 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.

      throws:
        IOException if an IOException occurs.
      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
      See Also:
        IOGroovyMethods#filterLine(java.io.Reader, java.io.Writer, groovy.lang.Closure)
      Since:
        1.6.8

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

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

      throws:
        IOException if an IOException occurs.
      Returns:
        the byte[] from that URL
      Since:
        1.7.1

    - #### public byte[] getBytes(Map<String, ?> 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
      throws:
        IOException if an IOException occurs.
      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.

      throws:
        IOException if an IOException occurs.
      Returns:
        the text from that URL
      Since:
        1.0

    - #### public String getText(Map<String, ?> 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
      throws:
        IOException if an IOException occurs.
      Parameters:
        `parameters` - connection parameters
      Returns:
        the text from that URL
      Since:
        1.8.1

    - #### 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.

      throws:
        IOException if an IOException occurs.
      Parameters:
        `charset` - opens the stream with a specified charset
      Returns:
        the text from that URL
      See Also:
        URLConnection.getInputStream
      Since:
        1.0

    - #### public String getText(Map<String, ?> parameters, String charset)

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

      throws:
        IOException if an IOException occurs.
      Parameters:
        `parameters` - connection parameters
        `charset` - opens the stream with a specified charset
      Returns:
        the text from that URL
      See Also:
        URLConnection.getInputStream
      Since:
        1.8.1

    - #### public BufferedInputStream newInputStream()

      Creates a buffered input stream for this URL.

      throws:
        IOException if an I/O error occurs while creating the input stream
      Returns:
        a BufferedInputStream for the URL
      Since:
        1.5.2

    - #### public BufferedInputStream newInputStream(Map<String, ?> 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
      throws:
        IOException if an I/O error occurs while creating the input stream
      Parameters:
        `parameters` - connection parameters
      Returns:
        a BufferedInputStream for the URL
      Since:
        1.8.1

    - #### public BufferedReader newReader()

      Creates a buffered reader for this URL.

      throws:
        MalformedURLException is thrown if the URL is not well-formed
      throws:
        IOException if an I/O error occurs while creating the input stream
      Returns:
        a BufferedReader for the URL
      Since:
        1.5.5

    - #### public BufferedReader newReader(Map<String, ?> 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
      throws:
        MalformedURLException is thrown if the URL is not well-formed
      throws:
        IOException if an I/O error occurs while creating the input stream
      Parameters:
        `parameters` - connection parameters
      Returns:
        a BufferedReader for the URL
      Since:
        1.8.1

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

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

      throws:
        MalformedURLException is thrown if the URL is not well-formed
      throws:
        IOException if an I/O error occurs while creating the input stream
      Parameters:
        `charset` - opens the stream with a specified charset
      Returns:
        a BufferedReader for the URL
      Since:
        1.5.5

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

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

      throws:
        MalformedURLException is thrown if the URL is not well-formed
      throws:
        IOException if an I/O error occurs while creating the input stream
      Parameters:
        `parameters` - connection parameters
        `charset` - opens the stream with a specified charset
      Returns:
        a BufferedReader for the URL
      Since:
        1.8.1

    - #### public List<String> readLines()

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

      throws:
        IOException if an IOException occurs.
      Returns:
        a List of lines
      See Also:
        IOGroovyMethods#readLines(java.io.Reader)
      Since:
        1.6.8

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

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

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

    - #### <T> public T splitEachLine(String regex, Closure<T> 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.

      throws:
        IOException if an IOException occurs.
      throws:
        java.util.regex.PatternSyntaxException if the regular expression's syntax is invalid
      Parameters:
        `regex` - the delimiting regular expression
        `closure` - a closure
      Returns:
        the last value returned by the closure
      See Also:
        IOGroovyMethods#splitEachLine(java.io.Reader, java.lang.String, groovy.lang.Closure)
      Since:
        1.6.8

    - #### <T> public T splitEachLine(Pattern pattern, Closure<T> 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.

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

    - #### <T> public T splitEachLine(String regex, String charset, Closure<T> 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.

      throws:
        IOException if an IOException occurs.
      throws:
        java.util.regex.PatternSyntaxException if the regular expression's syntax is invalid
      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
      See Also:
        IOGroovyMethods#splitEachLine(java.io.Reader, java.lang.String, groovy.lang.Closure)
      Since:
        1.6.8

    - #### <T> public T splitEachLine(Pattern pattern, String charset, Closure<T> 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.

      throws:
        IOException if an IOException occurs.
      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
      See Also:
        IOGroovyMethods#splitEachLine(java.io.Reader, java.util.regex.Pattern, groovy.lang.Closure)
      Since:
        1.6.8

    - #### <T> public T withInputStream(Closure<T> 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.

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

    - #### <T> public T withReader(Closure<T> 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.

      throws:
        IOException if an IOException occurs.
      Parameters:
        `closure` - the closure to invoke with the reader
      Returns:
        the value returned by the closure
      Since:
        1.5.2

    - #### <T> public T withReader(String charset, Closure<T> 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.

      throws:
        IOException if an IOException occurs.
      Parameters:
        `charset` - the charset used
        `closure` - the closure to invoke with the reader
      Returns:
        the value returned by the closure
      Since:
        1.5.6