org.jinterop.dcom.core
Class JISession

java.lang.Object
  extended by org.jinterop.dcom.core.JISession

public final class JISession
extends java.lang.Object

Representation of an active session with a COM server. All interface references being given out by the framework for a particular COM server are maintained by the session and an IJIComObject is associated with a single session only. Sessions are also responsible for the clean up once the system shuts down or IJIComObject go out of reference scope.

Please make sure that you call destroySession(JISession) after you are done using the session. This will ensure that any open sockets to COM server are closed.

Since:
1.0

Method Summary
static JISession createSession()
          Native Single Sign On capable session.
static JISession createSession(IJIAuthInfo authInfo)
          Creates a session with the authInfo of the user.
static JISession createSession(JISession session)
          Creates a new session using credentials of the sessionparameter.
static JISession createSession(java.lang.String domain, java.lang.String username, java.lang.String password)
          Creates a session.
static void destroySession(JISession session)
          Used to destroy the session, this release all references of the COM server and it's interfaces.
 boolean equals(java.lang.Object obj)
           
protected  void finalize()
           
 IJIAuthInfo getAuthInfo()
          Returns the IJIAuthInfo (if any) associated with this session.
 java.lang.String getDomain()
          Gets the domain of the user associated with this session.
 int getGlobalSocketTimeout()
          Returns the global timeout applied to all sockets opened from this session to COM Server.
 int getSessionIdentifier()
          Returns a unique identifier for this session.
 java.lang.String getUserName()
          Gets the user name associated with this session.
 int hashCode()
           
 boolean isNTLMv2Enabled()
           Flag indicating whether NTLMv2 security is enabled.
 boolean isSessionSecurityEnabled()
           Flag indicating whether session security is enabled.
 boolean isSSOEnabled()
          Returns whether this session is SSO or not.
 void setGlobalSocketTimeout(int timeout)
           Sets the timeout for all sockets opened to (not fro) the COM server for this session.
 void useNTLMv2(boolean enable)
           Sets the use of NTLMv2 Security (default is NTLM1).
 void useSessionSecurity(boolean enable)
           Sets the use of NTLM2 Session Security.
 
Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getAuthInfo

public IJIAuthInfo getAuthInfo()
Returns the IJIAuthInfo (if any) associated with this session.

Returns:

createSession

public static JISession createSession(IJIAuthInfo authInfo)
Creates a session with the authInfo of the user. This session is not yet attached to a COM server.

Parameters:
authInfo -
Returns:
Throws:
java.lang.IllegalArgumentException - if authInfo is null.
See Also:
JIComServer.JIComServer(JIClsid, JISession), JIComServer.JIComServer(JIProgId, JISession)

createSession

public static JISession createSession(java.lang.String domain,
                                      java.lang.String username,
                                      java.lang.String password)
Creates a session. This session is not yet attached to a COM server.

Parameters:
domain - domain of the user.
username - name of the user
password - password of the user.
Returns:
Throws:
java.lang.IllegalArgumentException - if any parameter is null.
See Also:
JIComServer.JIComServer(JIClsid, JISession), JIComServer.JIComServer(JIProgId, JISession)

createSession

public static JISession createSession(JISession session)
Creates a new session using credentials of the sessionparameter. The new session is not yet attached to a COM server.

Parameters:
session -
Returns:
See Also:
JIComServer.JIComServer(JIClsid, JISession), JIComServer.JIComServer(JIProgId, JISession)

createSession

public static JISession createSession()
Native Single Sign On capable session. Warning:

Returns:
See Also:
JIComServer.JIComServer(JIClsid, JISession), JIComServer.JIComServer(JIProgId, JISession)

isSSOEnabled

public boolean isSSOEnabled()
Returns whether this session is SSO or not.

Returns:

destroySession

public static void destroySession(JISession session)
                           throws JIException

Used to destroy the session, this release all references of the COM server and it's interfaces. It should be called in the end after the developer is done with the COM server.

Note that all interface references belonging to sessions linked to this session will also be destroyed.

Parameters:
session -
Throws:
JIException
See Also:
JIObjectFactory.narrowObject(org.jinterop.dcom.core.IJIComObject)

getUserName

public java.lang.String getUserName()
Gets the user name associated with this session.

Returns:

getDomain

public java.lang.String getDomain()
Gets the domain of the user associated with this session.

Returns:

getSessionIdentifier

public int getSessionIdentifier()
Returns a unique identifier for this session.

Returns:

equals

public boolean equals(java.lang.Object obj)
Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

finalize

protected void finalize()
Overrides:
finalize in class java.lang.Object

setGlobalSocketTimeout

public void setGlobalSocketTimeout(int timeout)

Sets the timeout for all sockets opened to (not fro) the COM server for this session. Default value is 0 (no timeout). The class level and the method level settings in case of IJIComObject override this timeout.

Parameters:
timeout - in millisecs
See Also:
IJIComObject.setInstanceLevelSocketTimeout(int), IJIComObject.call(JICallBuilder, int)

getGlobalSocketTimeout

public int getGlobalSocketTimeout()
Returns the global timeout applied to all sockets opened from this session to COM Server.

Returns:

useSessionSecurity

public void useSessionSecurity(boolean enable)

Sets the use of NTLM2 Session Security. Framework will use NTLM Packet Level Privacy and Sign\Seal all packets. Once the JIComServer is bound to this session (using any of the JIComServer constructors) the use of session security cannot be enabled or disabled.

Please note that session security can come at any available level of authentication (LM\NTLM\LMv2\NTLMv2). The framework currently only supports sign and seal at NTLMv1 level.

Whether to use NTLM1 or not is dictated by this field in the Windows Registry.

HKLM\System\CurrentControlSet\Control\Lsa\LmCompatibilityLevel

This article on MSDN talks more about it http://support.microsoft.com/default.aspx?scid=KB;en-us;239869

Parameters:
enable - true to enable, false to disable.

useNTLMv2

public void useNTLMv2(boolean enable)

Sets the use of NTLMv2 Security (default is NTLM1). This can be used in combination with useSessionSecurity method. Once the JIComServer is bound to this session (using any of the JIComServer constructors) the use of NTLMv2 security cannot be enabled or disabled.

Parameters:
enable - true to enable.

isSessionSecurityEnabled

public boolean isSessionSecurityEnabled()

Flag indicating whether session security is enabled.

Returns:
true for enabled.

isNTLMv2Enabled

public boolean isNTLMv2Enabled()

Flag indicating whether NTLMv2 security is enabled.

Returns:
true for enabled.