ucar.httpservices

Class HTTPSession

java.lang.Object

ucar.httpservices.HTTPSession

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

@ThreadSafe
public class HTTPSession
extends java.lang.Object
implements java.io.Closeable

A session is encapsulated in an instance of the class HTTPSession. The encapsulation is with respect to a specific HttpHost "realm", where the important part is is host+port. This means that once a session is specified, it is tied permanently to that realm.

A Session encapsulate a number of other objects:

• An instance of an Apache HttpClient.
• A http session id
• A RequestContext object; this also includes authentication: specifically a credential and a credentials provider.

Currently, it is assumed that only one set of credentials is needed, whether directly for server X or for server Y. This may change in the future.

As a rule, if the client gives an HTTPSession object to the "create method" procedures of HTTPFactory (e.g. HTTPFactory.Get or HTTPFactory.Post) then that creation call must specify a url that is "compatible" with the scope of the session. The method url is compatible if its host+port is the same as the session's host+port (=scope) and its scheme is compatible, where e.g. http is compatible with https (see HTTPAuthUtil.httphostCompatible)

If the HTTPFactory method creation call does not specify a session object, then one is created (and destroyed) behind the scenes along with the method.

Note that the term legalurl in the following code means that the url has reserved characters within identifieers in escaped form. This is particularly and issue for queries. Especially: ?x[0:5] is legal and the square brackets need not be encoded.

As of the move to Apache Httpclient 4.4 and later, the underlying HttpClient objects are generally immutable. This means that at least this class (HTTPSession) and the HTTPMethod class must store the relevant info and create the HttpClient and HttpMethod objects dynamically. This also means that when a parameter is changed (Agent, for example), any existing cached HttpClient must be thrown away and reconstructed using the change. As a rule, the HttpClient object will be created at the last minute so that multiple parameter changes can be effected without have to re-create the HttpClient for each parameter change. Also note that the immutable objects will be cached and reused if no parameters are changed.

Authorization We assume that the session supports two CredentialsProvider instances: one global to all HTTPSession objects and one specific to each HTTPSession object.

As an aside, authentication is a bit tricky because some authorization schemes use redirection. That is, the initial request is made to server X, but X says: goto to server Y" to get, say, and authorization token. Then Y says: return to X with this token and proceed.

SSL TBD.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	HTTPSession.Methods

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ACCEPT_ENCODING
protected static ucar.httpservices.HTTPSession.AuthControls	authcontrols
protected org.apache.http.client.config.RequestConfig	cachedconfig
protected boolean	cachevalid
protected static org.apache.http.HttpResponseInterceptor	CEKILL
protected boolean	closed
protected static ucar.httpservices.HTTPConnections	connmgr
protected static java.util.Map<java.lang.String,org.apache.http.client.entity.InputStreamFactory>	contentDecoderMap
protected static java.util.List<org.apache.http.HttpRequestInterceptor>	dbgreq
protected static java.util.List<org.apache.http.HttpResponseInterceptor>	dbgrsp
protected static java.util.Map<org.apache.http.auth.AuthScope,HTTPProviderFactory>	globalcredfactories
static java.lang.String	HEADER_USERAGENT
protected java.lang.String	identifier
protected java.util.Map<org.apache.http.auth.AuthScope,org.apache.http.client.CredentialsProvider>	localcreds
protected java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object>	localsettings
static org.slf4j.Logger	log
protected java.util.concurrent.ConcurrentSkipListSet<HTTPMethod>	methods
protected java.net.URI	requestURI
protected org.apache.http.auth.AuthScope	scope
protected java.net.URI	scopeURI
protected org.apache.http.impl.client.BasicAuthCache	sessioncache
protected org.apache.http.client.protocol.HttpClientContext	sessioncontext
protected java.lang.String	sessionURI
static boolean	TESTING
protected static boolean	USEPOOL Determine wether to use a Pooling connection manager or to manage a bunch of individual connections.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	HTTPSession()

Method Summary

Modifier and Type	Method and Description
protected static java.security.KeyStore	buildkeystore(java.lang.String keypath, java.lang.String keypassword)
protected static java.lang.String	checkCompressors(java.lang.String compressors)
HTTPSession	clearCookies()
HTTPSession	clearCredentialsCache()
HTTPSession	clearCredentialsCache(org.apache.http.auth.AuthScope template)
static void	clearGlobalCredentials() Remove any global credentials that have been previosly set with the setGlobalCredentials(Credentials) or setCredentialsProviderFactory(ucar.httpservices.HTTPProviderFactory, org.apache.http.auth.AuthScope) methods.
static void	clearkeystore()
void	clearState() Deprecated.
void	close() Close the session.
static HTTPUtil.InterceptRequest	debugRequestInterceptor()
static HTTPUtil.InterceptResponse	debugResponseInterceptor()
org.apache.http.auth.AuthScope	getAuthScope()
java.util.List<org.apache.http.cookie.Cookie>	getCookies()
org.apache.http.impl.client.BasicAuthCache	getCredentialsCache()
protected static int	getDPropInt(java.lang.String key)
static int	getGlobalMaxConnection()
static java.lang.Object	getGlobalSetting(java.lang.String key)
static java.lang.String	getGlobalUserAgent()
int	getMethodcount()
static int	getRetryCount() Deprecated.
java.lang.String	getSessionID() Extract the sessionid cookie value
java.lang.String	getSessionURI()
java.lang.String	getSessionURL() Deprecated.
java.lang.Object	getSetting(java.lang.String key)
protected void	init(org.apache.http.auth.AuthScope scope, java.lang.String actualurl)
boolean	isClosed()
protected static void	kill()
java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object>	mergedSettings()
static void	rebuildkeystore(java.lang.String path, java.lang.String pwd)
static void	removeGlobalCompression()
static void	resetInterceptors()
protected void	setAuthenticationAndProxy(org.apache.http.impl.client.HttpClientBuilder cb) Handle authentication and Proxy'ing
HTTPSession	setConnectionTimeout(int timeout)
HTTPSession	setCredentials(org.apache.http.auth.Credentials creds) It is convenient to be able to directly set the Credentials (not the provider) when those credentials are fixed.
HTTPSession	setCredentials(org.apache.http.auth.Credentials creds, org.apache.http.auth.AuthScope scope) It is convenient to be able to directly set the Credentials (not the provider) when those credentials are fixed.
HTTPSession	setCredentials(java.lang.String url, org.apache.http.auth.Credentials creds) Deprecated.
HTTPSession	setCredentialsProvider(org.apache.http.auth.AuthScope scope, org.apache.http.client.CredentialsProvider provider) Deprecated.
HTTPSession	setCredentialsProvider(org.apache.http.client.CredentialsProvider provider)
HTTPSession	setCredentialsProvider(org.apache.http.client.CredentialsProvider provider, org.apache.http.auth.AuthScope scope) This is the most general case
HTTPSession	setCredentialsProvider(java.lang.String url, org.apache.http.client.CredentialsProvider provider) Deprecated.
static void	setCredentialsProviderFactory(HTTPProviderFactory factory, org.apache.http.auth.AuthScope scope)
protected static void	setDefaults(java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object> props)
HTTPSession	setFollowRedirects(boolean tf) Enable/disable redirection following Default is yes.
static void	setGlobalCompression() Deprecated.
static void	setGlobalCompression(java.lang.String compressors)
static void	setGlobalConnectionTimeout(int timeout)
static void	setGlobalCredentials(org.apache.http.auth.Credentials creds) It is convenient to be able to directly set the Credentials (not the provider) when those credentials are fixed.
static void	setGlobalCredentials(org.apache.http.auth.Credentials creds, org.apache.http.auth.AuthScope scope) It is convenient to be able to directly set the Credentials (not the provider) when those credentials are fixed.
static void	setGlobalCredentials(java.lang.String url, org.apache.http.auth.Credentials creds) Deprecated.
static void	setGlobalCredentialsProvider(org.apache.http.auth.AuthScope scope, org.apache.http.client.CredentialsProvider provider) Deprecated.
static void	setGlobalCredentialsProvider(org.apache.http.client.CredentialsProvider provider) Deprecated.
static void	setGlobalCredentialsProvider(org.apache.http.client.CredentialsProvider provider, org.apache.http.auth.AuthScope scope) Deprecated.
static void	setGlobalCredentialsProvider(org.apache.http.client.CredentialsProvider provider, java.lang.String scheme) Deprecated.
static void	setGlobalCredentialsProvider(java.lang.String url, org.apache.http.client.CredentialsProvider provider) Deprecated.
static void	setGlobalFollowRedirects(boolean tf) Enable/disable redirection following Default is yes.
static void	setGlobalMaxConnections(int n)
static void	setGlobalMaxRedirects(int n) Set the max number of redirects to follow
static void	setGlobalProxy(java.lang.String host, int port) Deprecated.
static void	setGlobalRetryCount(int n)
static void	setGlobalSoTimeout(int timeout)
static void	setGlobalUserAgent(java.lang.String userAgent)
static void	setInterceptors(boolean print)
protected static void	setInterceptors(org.apache.http.impl.client.HttpClientBuilder cb)
HTTPSession	setMaxRedirects(int n) Set the max number of redirects to follow
void	setProxy(java.lang.String host, int port) Deprecated.
HTTPSession	setSoTimeout(int timeout)
HTTPSession	setUserAgent(java.lang.String agent)
HTTPSession	setUseSessions(boolean tf) Should we use sessionid's?
protected static void	track(HTTPSession session)
static void	validatestate()

Methods inherited from class java.lang.Object

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

Field Detail

TESTING

public static boolean TESTING

USEPOOL

protected static final boolean USEPOOL

Determine wether to use a Pooling connection manager or to manage a bunch of individual connections.

See Also:

Constant Field Values

HEADER_USERAGENT

public static final java.lang.String HEADER_USERAGENT

See Also:

Constant Field Values

ACCEPT_ENCODING

public static final java.lang.String ACCEPT_ENCODING

See Also:

Constant Field Values

log

public static final org.slf4j.Logger log

CEKILL

protected static org.apache.http.HttpResponseInterceptor CEKILL

dbgreq

protected static java.util.List<org.apache.http.HttpRequestInterceptor> dbgreq

dbgrsp

protected static java.util.List<org.apache.http.HttpResponseInterceptor> dbgrsp

connmgr

protected static ucar.httpservices.HTTPConnections connmgr

contentDecoderMap

protected static java.util.Map<java.lang.String,org.apache.http.client.entity.InputStreamFactory> contentDecoderMap

globalcredfactories

protected static java.util.Map<org.apache.http.auth.AuthScope,HTTPProviderFactory> globalcredfactories

authcontrols

protected static ucar.httpservices.HTTPSession.AuthControls authcontrols

sessionURI

protected java.lang.String sessionURI

scopeURI

protected java.net.URI scopeURI

scope

protected org.apache.http.auth.AuthScope scope

closed

protected boolean closed

localcreds

protected java.util.Map<org.apache.http.auth.AuthScope,org.apache.http.client.CredentialsProvider> localcreds

methods

protected java.util.concurrent.ConcurrentSkipListSet<HTTPMethod> methods

identifier

protected java.lang.String identifier

localsettings

protected java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object> localsettings

sessioncontext

protected org.apache.http.client.protocol.HttpClientContext sessioncontext

sessioncache

protected org.apache.http.impl.client.BasicAuthCache sessioncache

requestURI

protected java.net.URI requestURI

cachevalid

protected boolean cachevalid

cachedconfig

protected org.apache.http.client.config.RequestConfig cachedconfig

Constructor Detail

HTTPSession

protected HTTPSession()
               throws HTTPException

Throws:

HTTPException

Method Detail

getDPropInt

protected static int getDPropInt(java.lang.String key)

setDefaults

protected static void setDefaults(java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object> props)

buildkeystore

protected static final java.security.KeyStore buildkeystore(java.lang.String keypath,
                                                            java.lang.String keypassword)

setGlobalUserAgent

public static void setGlobalUserAgent(java.lang.String userAgent)

getGlobalUserAgent

public static java.lang.String getGlobalUserAgent()

setGlobalMaxConnections

public static void setGlobalMaxConnections(int n)

getGlobalMaxConnection

public static int getGlobalMaxConnection()

setGlobalConnectionTimeout

public static void setGlobalConnectionTimeout(int timeout)

setGlobalSoTimeout

public static void setGlobalSoTimeout(int timeout)

setGlobalFollowRedirects

public static void setGlobalFollowRedirects(boolean tf)

Enable/disable redirection following Default is yes.

setGlobalMaxRedirects

public static void setGlobalMaxRedirects(int n)

Set the max number of redirects to follow

Parameters:

n -

getGlobalSetting

public static java.lang.Object getGlobalSetting(java.lang.String key)

setGlobalCompression

public static void setGlobalCompression(java.lang.String compressors)

removeGlobalCompression

public static void removeGlobalCompression()

checkCompressors

protected static java.lang.String checkCompressors(java.lang.String compressors)

setCredentialsProviderFactory

public static void setCredentialsProviderFactory(HTTPProviderFactory factory,
                                                 org.apache.http.auth.AuthScope scope)
                                          throws HTTPException

Parameters:

factory - the credentials provider factory

scope - where to use it (i.e. on what host)

Throws:

HTTPException

setGlobalCredentials

public static void setGlobalCredentials(org.apache.http.auth.Credentials creds)
                                 throws HTTPException

It is convenient to be able to directly set the Credentials (not the provider) when those credentials are fixed. Scope defaults to ANY

Parameters:

creds -

Throws:

HTTPException

setGlobalCredentials

public static void setGlobalCredentials(org.apache.http.auth.Credentials creds,
                                        org.apache.http.auth.AuthScope scope)
                                 throws HTTPException

It is convenient to be able to directly set the Credentials (not the provider) when those credentials are fixed.

Parameters:

creds -

scope - where to use it (i.e. on what host)

Throws:

HTTPException

clearGlobalCredentials

public static void clearGlobalCredentials()

Remove any global credentials that have been previosly set with the setGlobalCredentials(Credentials) or setCredentialsProviderFactory(ucar.httpservices.HTTPProviderFactory, org.apache.http.auth.AuthScope) methods.

setGlobalRetryCount

public static void setGlobalRetryCount(int n)

init

protected void init(org.apache.http.auth.AuthScope scope,
                    java.lang.String actualurl)
             throws HTTPException

Throws:

HTTPException

setInterceptors

protected static void setInterceptors(org.apache.http.impl.client.HttpClientBuilder cb)

getAuthScope

public org.apache.http.auth.AuthScope getAuthScope()

getSessionURI

public java.lang.String getSessionURI()

getSessionID

public java.lang.String getSessionID()

Extract the sessionid cookie value

Returns:

sessionid string

setUserAgent

public HTTPSession setUserAgent(java.lang.String agent)

setSoTimeout

public HTTPSession setSoTimeout(int timeout)

setConnectionTimeout

public HTTPSession setConnectionTimeout(int timeout)

setMaxRedirects

public HTTPSession setMaxRedirects(int n)

Set the max number of redirects to follow

Parameters:

n -

setFollowRedirects

public HTTPSession setFollowRedirects(boolean tf)

Enable/disable redirection following Default is yes.

setUseSessions

public HTTPSession setUseSessions(boolean tf)

Should we use sessionid's?

Parameters:

tf -

getCookies

public java.util.List<org.apache.http.cookie.Cookie> getCookies()

clearCookies

public HTTPSession clearCookies()

clearCredentialsCache

public HTTPSession clearCredentialsCache()

clearCredentialsCache

public HTTPSession clearCredentialsCache(org.apache.http.auth.AuthScope template)

getCredentialsCache

public org.apache.http.impl.client.BasicAuthCache getCredentialsCache()

getSetting

public java.lang.Object getSetting(java.lang.String key)

close

public void close()

Close the session. This implies closing any open methods.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

setCredentialsProvider

public HTTPSession setCredentialsProvider(org.apache.http.client.CredentialsProvider provider)
                                   throws HTTPException

Parameters:

provider -

Throws:

HTTPException

setCredentialsProvider

public HTTPSession setCredentialsProvider(org.apache.http.client.CredentialsProvider provider,
                                          org.apache.http.auth.AuthScope scope)
                                   throws HTTPException

This is the most general case

Parameters:

provider - the credentials provider

scope - where to use it (i.e. on what host+port)

Throws:

HTTPException

setCredentials

public HTTPSession setCredentials(org.apache.http.auth.Credentials creds)
                           throws HTTPException

It is convenient to be able to directly set the Credentials (not the provider) when those credentials are fixed. Scope defaults to ANY

Parameters:

creds -

Throws:

HTTPException

setCredentials

public HTTPSession setCredentials(org.apache.http.auth.Credentials creds,
                                  org.apache.http.auth.AuthScope scope)
                           throws HTTPException

It is convenient to be able to directly set the Credentials (not the provider) when those credentials are fixed.

Parameters:

creds -

scope - where to use it (i.e. on what host)

Throws:

HTTPException

setAuthenticationAndProxy

protected void setAuthenticationAndProxy(org.apache.http.impl.client.HttpClientBuilder cb)
                                  throws HTTPException

Handle authentication and Proxy'ing

Parameters:

cb -

Throws:

HTTPException

mergedSettings

public java.util.Map<ucar.httpservices.HTTPSession.Prop,java.lang.Object> mergedSettings()

isClosed

public boolean isClosed()

getMethodcount

public int getMethodcount()

track

protected static void track(HTTPSession session)

setInterceptors

public static void setInterceptors(boolean print)

resetInterceptors

public static void resetInterceptors()

debugRequestInterceptor

public static HTTPUtil.InterceptRequest debugRequestInterceptor()

debugResponseInterceptor

public static HTTPUtil.InterceptResponse debugResponseInterceptor()

clearkeystore

public static void clearkeystore()

rebuildkeystore

public static void rebuildkeystore(java.lang.String path,
                                   java.lang.String pwd)

setGlobalCredentialsProvider

@Deprecated
public static void setGlobalCredentialsProvider(org.apache.http.auth.AuthScope scope,
                                                            org.apache.http.client.CredentialsProvider provider)
                                                     throws HTTPException

Deprecated.

Throws:

HTTPException

setGlobalCredentialsProvider

@Deprecated
public static void setGlobalCredentialsProvider(java.lang.String url,
                                                            org.apache.http.client.CredentialsProvider provider)
                                                     throws HTTPException

Deprecated.

Throws:

HTTPException

setGlobalCredentials

@Deprecated
public static void setGlobalCredentials(java.lang.String url,
                                                    org.apache.http.auth.Credentials creds)
                                             throws HTTPException

Deprecated.

Throws:

HTTPException

setCredentials

@Deprecated
public HTTPSession setCredentials(java.lang.String url,
                                              org.apache.http.auth.Credentials creds)
                                       throws HTTPException

Deprecated.

Throws:

HTTPException

setCredentialsProvider

@Deprecated
public HTTPSession setCredentialsProvider(java.lang.String url,
                                                      org.apache.http.client.CredentialsProvider provider)
                                               throws HTTPException

Deprecated.

Throws:

HTTPException

setCredentialsProvider

@Deprecated
public HTTPSession setCredentialsProvider(org.apache.http.auth.AuthScope scope,
                                                      org.apache.http.client.CredentialsProvider provider)
                                               throws HTTPException

Deprecated.

Throws:

HTTPException

getRetryCount

@Deprecated
public static int getRetryCount()

Deprecated.

setGlobalCompression

@Deprecated
public static void setGlobalCompression()

Deprecated.

setGlobalProxy

@Deprecated
public static void setGlobalProxy(java.lang.String host,
                                              int port)

Deprecated.

setProxy

@Deprecated
public void setProxy(java.lang.String host,
                                 int port)

Deprecated.

setGlobalCredentialsProvider

@Deprecated
public static void setGlobalCredentialsProvider(org.apache.http.client.CredentialsProvider provider,
                                                            java.lang.String scheme)
                                                     throws HTTPException

Deprecated.

Throws:

HTTPException

clearState

@Deprecated
public void clearState()

Deprecated.

getSessionURL

@Deprecated
public java.lang.String getSessionURL()

Deprecated.

kill

protected static void kill()

validatestate

public static void validatestate()

setGlobalCredentialsProvider

@Deprecated
public static void setGlobalCredentialsProvider(org.apache.http.client.CredentialsProvider provider)
                                                     throws HTTPException

Deprecated.

Parameters:

provider -

Throws:

HTTPException

setGlobalCredentialsProvider

@Deprecated
public static void setGlobalCredentialsProvider(org.apache.http.client.CredentialsProvider provider,
                                                            org.apache.http.auth.AuthScope scope)
                                                     throws HTTPException

Deprecated.

This is the most general case

Parameters:

provider - the credentials provider

scope - where to use it (i.e. on what host)

Throws:

HTTPException