Friday June 23, 2006
Friday June 23, 2006 Now to explain what is checked in ... the main purpose of the whole project 
Essentially a simple framework for authentication has been checked in. Let us take a look at the Classes involved.
There is a AuthenticationManager in net.java.dev.xmpp.client.core , which handles the actual session creation and management.
In the collab api , you create a collab session using a CollaborationSessionFactory - which delegates the actual session creation to an instance of CollaborationSessionProvider.
The default CollaborationSessionProvider is org.netbeans.lib.collab.xmpp.XMPPSessionProvider - this allows us to create a direct socket based session to a XMPP server.
Other CollaborationSessionProvider that can be used are :
To use a non-default provider , you will just need to specify the classname as the parameter to CollaborationSessionFactory constructor (in our case , constructor of AuthenticationManager) ! Rest of the details are taken care of by the collab api - and it exposes a uniform behaviour irrespective of the underlying transport : even when the underlying transport is not a dedicated socket stream like in httpbind case !
Ok , almost ... there are a couple of little details a user still has to take care of .... let us finish those of too.
If in the process of session establishment , an untrusted certificate is provided as part of TLS , the decision whether to accept the certificate or not depends on what the provided CollaborationSessionListener says.
That is , if the listener is an instance of org.netbeans.lib.collab.SecureSessionListener , then the corresponding "onX509Certificate" method is invoked ... else the certificate is treated as untrusted and session terminated.
If the service URL points to the form "host:port" , the collab api uses that directly as the destination XMPP server/port.
In case it is of the form "domain" , it tries two things one after the other.
ProxySessionProvider and HTTPBindSessionProvider use the service URL as a way to obtain required parameters.
In all the other providers , the service URL is just the destination "host : port" (or domain in case you want to do a dynamic lookup of the XMPP host servicing that domain).
In these two providers , the semantics are different , let us see how :
<protocol>://<proxy host>:<proxy port>?(name=value)(&name=value)*
The protocol can be one of "socks" or "http"/"https" : socks will tunnel through a socks proxy , while http or https will tunnel using http CONNECT.
The query names currently handled are :
https://myproxyhost:8080?keepalive=120&authname=test&password=pass&service=xmpp.sun.com&usessl=false
The actual query parameters are defined in org.netbeans.lib.collab.xmpp.httpbind.HTTPBindConstants ... and allows for a wide range of customisations. The only mandatory query parameter is the "to" parameter.
This specifies the domain the user wants to log into : and should be serviced by the specified httpbind connection manager.
Another important point related to httpbind is related to proxy support.
The default two ConnectionProvider's for httpbind do not support proxies directly.
But , they use URLConnection to get to the httpbind gateway , so you can specify the appropriate proxy using the corresponding java properties and expect them to be used.
The main reason why they do not support it is 'cos the 1.4 java.net.* code does not provide a way to explictly specify a proxy... as and when the api moves completely to 1.5 , this implementation will get revised.
Ofcourse , you can always write and provide a custom ConnectionProvider in the service url which picks up the proxies and uses it !
Please note that "proxytype" and "proxyhostport" is expected to be provided even if you explictly set the java proxy vairables ... this is so that is the collab api's move to 1.5 and start using the java.net.Proxy class , the client code should not need to be modified.
So a sample HTTPBindSessionProvider service URL would be : https://my_gateway_host:port/codebase/httpbind?max_buffered_bytes=1000000&max_buffered_packets=1000&to=sun.com&proxytype=http&proxyhostport=myproxyhost:port
Other than specific customisation's , there is nothing much else that needs to be taken care of !
[Technorati Tag: XMPP]
[Technorati Tag: Sun IM api]
[Technorati Tag: xmpp-im-client]
Essentially a simple framework for authentication has been checked in. Let us take a look at the Classes involved.
There is a AuthenticationManager in net.java.dev.xmpp.client.core , which handles the actual session creation and management.
In the collab api , you create a collab session using a CollaborationSessionFactory - which delegates the actual session creation to an instance of CollaborationSessionProvider.
The default CollaborationSessionProvider is org.netbeans.lib.collab.xmpp.XMPPSessionProvider - this allows us to create a direct socket based session to a XMPP server.
Other CollaborationSessionProvider that can be used are :
- org.netbeans.lib.collab.xmpp.XMPPSecureSessionProvider - This provider allows you to use legacy SSL to the server. This is a deprecated jabber protocol where the server always listens on SSL mode : like what you have in http/https case.
- org.netbeans.lib.collab.xmpp.XMPPComponentSessionProvider - This allows you to create a 'trusted' component session : please refer to JEP 0114 for technical info.
- org.netbeans.lib.collab.xmpp.ProxySessionProvider - This provider allows you to create a XMPP session tunneling through HTTPS or SOCKS proxy. The actual proxy to talk to is picked up from the service URL.
- org.netbeans.lib.collab.xmpp.XMPPSecureComponentSessionProvider - allows creation of component session when server is in legacy SSL mode.
- org.netbeans.lib.collab.xmpp.httpbind.HTTPBindSessionProvider - allows creation of a HTTP based XMPP session as per JEP 0124. The connection related info is picked up from the service URL.
To use a non-default provider , you will just need to specify the classname as the parameter to CollaborationSessionFactory constructor (in our case , constructor of AuthenticationManager) ! Rest of the details are taken care of by the collab api - and it exposes a uniform behaviour irrespective of the underlying transport : even when the underlying transport is not a dedicated socket stream like in httpbind case !
Ok , almost ... there are a couple of little details a user still has to take care of .... let us finish those of too.
If in the process of session establishment , an untrusted certificate is provided as part of TLS , the decision whether to accept the certificate or not depends on what the provided CollaborationSessionListener says.
That is , if the listener is an instance of org.netbeans.lib.collab.SecureSessionListener , then the corresponding "onX509Certificate" method is invoked ... else the certificate is treated as untrusted and session terminated.
If the service URL points to the form "host:port" , the collab api uses that directly as the destination XMPP server/port.
In case it is of the form "domain" , it tries two things one after the other.
- It tries to do a dns query for the specified "domain" to try to find out if there is a xmpp service registered for it. If yes , it uses that as the destination server. This way , the actual xmpp server hosting a domain could be decoupled from the domain itself. Refer here for more details.
- If (1) is not the case , the api treats "domain" as XMPP host with default port of "5222".
ProxySessionProvider and HTTPBindSessionProvider use the service URL as a way to obtain required parameters.
In all the other providers , the service URL is just the destination "host : port" (or domain in case you want to do a dynamic lookup of the XMPP host servicing that domain).
In these two providers , the semantics are different , let us see how :
- ProxySessionProvider
<protocol>://<proxy host>:<proxy port>?(name=value)(&name=value)*
The protocol can be one of "socks" or "http"/"https" : socks will tunnel through a socks proxy , while http or https will tunnel using http CONNECT.
The query names currently handled are :
- "keepalive" : After authentication succeeds , the client will send whitespace pings to the server after each keepalive interval : this is so that intermediate proxies do not terminate the connection assuming it is inactive.
- "authname" , "password" : The authentication credentials to talk to the proxy.
- "service" : The 'actual service url' !
- "usessl" : Whether to use legacy SSL to talk to the XMPP server after tunneling through the proxy.
https://myproxyhost:8080?keepalive=120&authname=test&password=pass&service=xmpp.sun.com&usessl=false
- HTTPBindSessionProvider
The actual query parameters are defined in org.netbeans.lib.collab.xmpp.httpbind.HTTPBindConstants ... and allows for a wide range of customisations. The only mandatory query parameter is the "to" parameter.
This specifies the domain the user wants to log into : and should be serviced by the specified httpbind connection manager.
Another important point related to httpbind is related to proxy support.
The default two ConnectionProvider's for httpbind do not support proxies directly.
But , they use URLConnection to get to the httpbind gateway , so you can specify the appropriate proxy using the corresponding java properties and expect them to be used.
The main reason why they do not support it is 'cos the 1.4 java.net.* code does not provide a way to explictly specify a proxy... as and when the api moves completely to 1.5 , this implementation will get revised.
Ofcourse , you can always write and provide a custom ConnectionProvider in the service url which picks up the proxies and uses it !
Please note that "proxytype" and "proxyhostport" is expected to be provided even if you explictly set the java proxy vairables ... this is so that is the collab api's move to 1.5 and start using the java.net.Proxy class , the client code should not need to be modified.
So a sample HTTPBindSessionProvider service URL would be : https://my_gateway_host:port/codebase/httpbind?max_buffered_bytes=1000000&max_buffered_packets=1000&to=sun.com&proxytype=http&proxyhostport=myproxyhost:port
Other than specific customisation's , there is nothing much else that needs to be taken care of !
[Technorati Tag: XMPP]
[Technorati Tag: Sun IM api]
[Technorati Tag: xmpp-im-client]