Project

Namespaces

Public Vars

urlocal.api

The public API of the urlocal library.

cache-check-interval-secs

(cache-check-interval-secs)

Returns the current cache check interval, in seconds.

view source

cache-dir

(cache-dir)

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

view source

cache-name

(cache-name)

Returns the current name of the cache as a String.

view source

input-stream

(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
  • :follow-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.

view source

remove-cache-entry!

(remove-cache-entry! url)

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

Throws on IO errors.

view source

reset-cache!

(reset-cache!)

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

Throws on IO errors.

view source

set-cache-check-interval-secs!

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

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

view source

set-cache-name!

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

view source