nesstar.api
Class Protocol

java.lang.Object
  nesstar.api.Protocol

public class Protocol
extends Object

Client/Server protocol.

This class contains the static methods used to initialise and change the settings of the client/server protocol.

The Protocol object encapsulate all the information associated with the accesses to one or more remote Server on behalf of a certain user identity, in particular:

• the session IDs
• the cache of downloaded objects

Protocols are associated with threads so that all API operations that take place on a certain thread will use the same protocol and therefore the same sessions and caches.

To create a Protocol and associate it with the current thread the application uses newProtocol().

An application can associate the same Protocol to additional threads calling setAsCurrent().

Web clients need to associate protocols with corresponding user sessions. They can do so using ServletUtils.setProtocol(javax.servlet.http.HttpSession).

API operations can return access control challenges that need to be displayed to the user.

Clients such as the web clients that communicate with the user using more than one channel need a way of addressing these challenges correctly.

They can do so by associating a different ExecutorLog with every thread using setExecutorLog(BasicExecutorLog).

Field Summary

static String

ACCEPTEDLANGUAGE

Method Summary

void	finalize()
static String	getAcceptedLanguage()
static Protocol	getCurrent()
static NetDB	getDB()
static BasicExecutorLog	getExecutorLog()
static BasicExecutorLog	getExecutorLog(Bookmark bookmark, BasicExecutorLog executor)
static String	getHeader(String header)
static Vector	getHeaders()
static org.apache.commons.httpclient.HttpClient	getHttpClient()
static int	getHTTPTimeoutInSecs()
static int	getHTTPTimeoutInSecs(int timeoutInSecs)
static String	getLocalDBContents()
static RDFDB	getOpsDB()
static void	init() Default init.
static void	init(String saxParser, String httpProxyHost, int httpProxyPort, String socksProxyHost, int socksProxyPort, Class htmlViewerClass) Initialise protocol, this method should be called at the beginning of the program.
static void	init(String saxParser, String httpProxyHost, int httpProxyPort, String socksProxyHost, int socksProxyPort, Class htmlViewerClass, String localObjsProxy) Initialise protocol, this method should be called at the beginning of the program.
static Protocol	newProtocol() Create a new Protocol object and associate it with the current thread.
static Protocol	newProtocol(String id) Create a new Protocol object and associate it with the current thread.
static void	setAcceptedLanguage(String languages)
void	setAsCurrent() Set this protocol as the current one
static void	setCredentials(String realm, String host, String username, String password) Sets the credentials for the current protocol.
static void	setExecutorLog(BasicExecutorLog executor) Set the executor log to use for API calls that will take place in the current context for the current thread.
static void	setFallBackLanguage(String locale)
static void	setHeader(String header, String value)
static void	setHTMLViewerClass(Class htmlViewerClass) Set the class that implements the nesstar.api.HTMLViewer interface.
static void	setHTTPTimeoutInSecs(int timeoutInSecs) Set the timeout in seconds for HTTP connections for the current protocol.
static void	setProxies(String httpProxyHost, int httpProxyPort, String socksProxyHost, int socksProxyPort) Sets the proxies attribute for the current protocol.
static void	setProxyCredentials(String realm, String proxyHost, String username, String password) Sets the proxy credentials for the current protocol.
static void	setTimeoutInSecs(long timeoutInSecs) Set the timeout in seconds for the proxy objects to expire from the cache.
String	toString()
static void	unbind() Unbind the current protocol and executor log from the current thread.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ACCEPTEDLANGUAGE

public static final String ACCEPTEDLANGUAGE

See Also:

Constant Field Values

Method Detail

setProxies

public static void setProxies(String httpProxyHost,
                              int httpProxyPort,
                              String socksProxyHost,
                              int socksProxyPort)

Sets the proxies attribute for the current protocol.

Parameters:

httpProxyHost - the Http Proxy Host, if set to null no Http proxy will be used.

httpProxyPort - the Http Proxy Port, e.g. 8080.

socksProxyHost - the Socks Proxy Host, if set to null no Socks proxy will be used.

socksProxyPort - the Socks Proxy Port.

Bug:

this should be done only once for all protocols.

setCredentials

public static void setCredentials(String realm,
                                  String host,
                                  String username,
                                  String password)

Sets the credentials for the current protocol.

Parameters:

realm -

host -

username -

password -

setProxyCredentials

public static void setProxyCredentials(String realm,
                                       String proxyHost,
                                       String username,
                                       String password)

Sets the proxy credentials for the current protocol.

Parameters:

realm -

proxyHost -

username -

password -

setHTMLViewerClass

public static void setHTMLViewerClass(Class htmlViewerClass)

Set the class that implements the nesstar.api.HTMLViewer interface.
It will be used to display the results of accessing non-nesstar URLs.

Parameters:

htmlViewerClass - a class

getOpsDB

public static RDFDB getOpsDB()

Returns:

the DB that contains the mappings for the local operations

getDB

public static NetDB getDB()

Returns:

the default DB that contains the objects read-in from the Net associated with the current Protocol instance

init

public static void init(String saxParser,
                        String httpProxyHost,
                        int httpProxyPort,
                        String socksProxyHost,
                        int socksProxyPort,
                        Class htmlViewerClass,
                        String localObjsProxy)
                 throws Exception

Initialise protocol, this method should be called at the beginning of the program.
It can not be used to change the settings at a later time.

Parameters:

saxParser - the name of the class that implements the sax parser, ex: "com.sun.xml.parser.Parser"

httpProxyHost - the http proxy server host name, ex: "wwwcache.essex.ac.uk", if it's equal to null no proxy is used

httpProxyPort - the http proxy server port number, ex: 8080

socksProxyHost - the SOCKS proxy server host name, ex: "socks.mydomain.com", if it's equal to null no proxy is used

socksProxyPort - the SOCKS proxy server port number, ex: 1080

htmlViewerClass - a class that implements the nesstar.api.HTMLViewer interface that will be used to display the results of accessing non-nesstar URLs

localObjsProxy - the URL of the proxy that will redirect calls to the local client obj

Throws:

Exception

Bug:

this doesn't set up the proxies.

init

public static void init(String saxParser,
                        String httpProxyHost,
                        int httpProxyPort,
                        String socksProxyHost,
                        int socksProxyPort,
                        Class htmlViewerClass)
                 throws Exception

Initialise protocol, this method should be called at the beginning of the program.
It can also be used to change the settings at a later time.

Parameters:

saxParser - the name of the class that implements the sax parser, ex: "com.sun.xml.parser.Parser"

httpProxyHost - the http proxy server host name, ex: "wwwcache.essex.ac.uk", if it's equal to null no proxy is used

httpProxyPort - the http proxy server port number, ex: 8080

socksProxyHost - the SOCKS proxy server host name, ex: "socks.mydomain.com", if it's equal to null no proxy is used

socksProxyPort - the SOCKS proxy server port number, ex: 1080

htmlViewerClass - a class that implements the nesstar.api.HTMLViewer interface that will be used to display the results of accessing non-nesstar URLs

Throws:

Exception

init

public static void init()
                 throws Exception

Default init.

Throws:

Exception

setTimeoutInSecs

public static void setTimeoutInSecs(long timeoutInSecs)

Set the timeout in seconds for the proxy objects to expire from the cache. This setting currently applies to all protocols.

Parameters:

the - new timeout in seconds

setHTTPTimeoutInSecs

public static void setHTTPTimeoutInSecs(int timeoutInSecs)

Set the timeout in seconds for HTTP connections for the current protocol.

Parameters:

the - new timeout in seconds

getHTTPTimeoutInSecs

public static int getHTTPTimeoutInSecs()

Returns:

the current timeout in seconds for HTTP connections for the current protocol.

getHTTPTimeoutInSecs

public static int getHTTPTimeoutInSecs(int timeoutInSecs)

Returns:

the current timeout in seconds for HTTP connections for the current protocol or the passed timeout if it is <=0.

setExecutorLog

public static void setExecutorLog(BasicExecutorLog executor)
                           throws Exception

Set the executor log to use for API calls that will take place in the current context for the current thread.

Parameters:

executor - the executor to use

Throws:

Exception

getExecutorLog

public static BasicExecutorLog getExecutorLog()

Returns:

the executor log for the current context and thread

getExecutorLog

public static BasicExecutorLog getExecutorLog(Bookmark bookmark,
                                              BasicExecutorLog executor)
                                       throws Exception

Returns:

the executor log for the current context and thread

Throws:

Exception

newProtocol

public static Protocol newProtocol()
                            throws Exception

Create a new Protocol object and associate it with the current thread.

Returns:

the new Protocol

Throws:

Exception

newProtocol

public static Protocol newProtocol(String id)
                            throws Exception

Create a new Protocol object and associate it with the current thread.

Parameters:

id - a (not necessarily unique) id associated to this protocol, used for logging purposes.

Returns:

the new Protocol

Throws:

Exception

setHeader

public static void setHeader(String header,
                             String value)

setAcceptedLanguage

public static void setAcceptedLanguage(String languages)

setFallBackLanguage

public static void setFallBackLanguage(String locale)

getHeaders

public static Vector getHeaders()

getHeader

public static String getHeader(String header)

getAcceptedLanguage

public static String getAcceptedLanguage()

setAsCurrent

public void setAsCurrent()

Set this protocol as the current one

unbind

public static void unbind()

Unbind the current protocol and executor log from the current thread.

getCurrent

public static Protocol getCurrent()

Returns:

the protocol associated to the current thread

getHttpClient

public static org.apache.commons.httpclient.HttpClient getHttpClient()

getLocalDBContents

public static String getLocalDBContents()
                                 throws Exception

Returns:

what should be saved in the localDB: Servers, their catalogs property and the linked Catalog objects.

Throws:

Exception

toString

public String toString()

Overrides:

toString in class Object

finalize

public void finalize()

Overrides:

finalize in class Object