urlocal.api — com.github.pmonks/urlocal 1.0.52

The public API of the urlocal library.

cache-check-interval-secs clj

(cache-check-interval-secs)

Returns the current cache check interval, in seconds.

cache-dir clj

(cache-dir)

Returns the current cache directory as a java.io.File.

cache-name clj

(cache-name)

Returns the current name of the cache as a String.

input-stream clj

(input-stream url)

(input-stream url
              {:keys [connect-timeout read-timeout follow-redirects?
                      retry-when-throttled? max-retry-after request-headers
                      return-cached-content-on-exception?]
               :or {connect-timeout 1000
                    read-timeout 1000
                    follow-redirects? false
                    retry-when-throttled? false
                    max-retry-after 10
                    request-headers {"User-Agent" "com.github.pmonks/urlocal"}
                    return-cached-content-on-exception? true}
               :as opts})

Retrieves the content from url and caches it, returning an InputStream for the content. url may be a String, java.net.URL or java.net.URI. Returns nil if url is nil or unsupported (i.e. is not an http(s) URL).

opts provides these tunables, all of them optional:

• :connect-timeout (int, default 1000): the maximum number of milliseconds to wait when establishing the socket connection
• :read-timeout (int, default 1000): the maximum number of milliseconds to wait when reading content from the socket connection
• :follows-redirects? (boolean, default false): whether to follow a single redirect (HTTP status codes 301, 302) if the server issues one (more than one redirect will throw an exception)
• :retry-when-throttled? (boolean, default false): whether to automatically handle throttled HTTP requests (HTTP status code 429), by sleeping as requested by the Retry-After HTTP response header, then retrying the request
• :max-retry-after (int, default 10): the maximum number of seconds to sleep when waiting to retry a throttled request
• :request-headers (a Map with String keys and values): a map of request headers to send along with the request
• return-cached-content-on-exception? (boolean, default true): whether (potentially stale) cached content should be returned if it's available, and an exception occurs while checking for staleness

Throws on IO errors.

remove-cache-entry! clj

(remove-cache-entry! url)

Removes the cache entry for the given url, if it exists. Returns nil.

Throws on IO errors.

reset-cache! clj

(reset-cache!)

Resets (i.e. deletes) the local cache, returning nil.

Throws on IO errors.

set-cache-check-interval-secs! clj

(set-cache-check-interval-secs! cache-check-interval-secs)

Sets the cache check interval, in seconds. Default is 86400 (24 hours). Returns nil.

set-cache-name! clj

(set-cache-name! n)

Sets the name of the cache to n (which ends up being part of the cache directory's name), and returns nil. Default name is urlocal.

Notes:

• n must not be blank.
• the new cache directory may not be empty if it exists and was previously populated.
• setting a new name after a previously named cache has already been populated will 'orphan' the prior cache. To avoid this, you should call reset-cache! prior to setting a new name.

Throws on IO errors.