com.realtime.xmpp
Class XmppSession

java.lang.Object
  |
  +--com.realtime.xmpp.XmppSession

public class XmppSession

extends java.lang.Object

Opens and manages an XMPP stream connection with a Jabber server. Use open() to establish a connection, and then authenticate using packets appropriate to the namespace you are using.

When a connection is opened, a reader Thread is created that sits on the input stream and processes the raw XML into SAX events. Classes that implement the SAX ContentHandler interface transform the SAX event stream into object graphs. Each transformer has a callback mechanism that listeners can register with to receive incoming packets.

Typical use of the XmppSession class using a transformer is:

 // open up the connection
 XmppSession session = new XmppSession( "localhost", 5222, COMPONENT_ACCEPT_NAMESPACE );
 Xmpp2DomTransformer transformer = new Xmpp2DomTransformer( session );
 stream.open();
 
 // send the accept component handshake
 String sSessionId = session.getAttribute( "id" );
 HandshakeRequest request = new HandshakeRequest( sSessionId, "secret" );
 Element response = new DomPacketSender( transformer ).send( request );
 

Each outgoing packet should be written using a single call to write(). In the above example, the DomPacketSender took care of this task.

This class is thread safe.

Version:

1.0 Copyright © 2002 Real Time Entertainment Group, LLC - All rights reserved.

Author:

Mike Prince

Nested Class Summary

protected class

XmppSession.ParserThread Daemon thread to parse incoming packets through the SaxEventManager.

Field Summary

static java.lang.String	COMPONENT_ACCEPT_NAMESPACE The Jabber component accept namespace for components initiating communications with a host.
static java.lang.String	COMPONENT_CONNECT_NAMESPACE The Jabber component connect namespace, for hosts initiating a connection to a component.
static long	DEFAULT_OPEN_TIMEOUT The default amount of time, in milliseconds, that it should take for the jabber server to respond to the opening XML <stream:stream> element.
protected static java.lang.String	DEFAULT_PARSER_NAME Default XML parser name.
static java.lang.String	JABBER_CLIENT_NAMESPACE The Jabber client namespace for node to host, and host to node communications.
static java.lang.String	JABBER_SERVER_NAMESPACE The Jabber host to host communications namespace.
protected boolean	m_bOpen Are we open for streaming XMPP packets?
protected XmlStream	m_connection Our connection to jabber.
protected XmlStreamFactory	m_connectionFactory Our connection factory.
protected XmppSession.ParserThread	m_currentParserThread Our current parser thread.
protected java.lang.Object	m_openMonitor A monitor for threads to wait on pending the session being opened.
protected java.io.OutputStream	m_out XML stream to the Jabber server.
protected SaxEventManager	m_saxEventManager Object to handle SAX events during XMPP processing.
protected java.lang.Object	m_sessionListenerMutex Mutex to synchronize modifications to the session listener list.
protected XmppSessionListener[]	m_sessionListeners Session lifecycle listeners.
protected java.lang.String	m_sNamespace The Jabber namespace to use.
protected java.util.List	m_transformers XML/XMPP transformers.

Constructor Summary

XmppSession(java.lang.String sHost, int nPort, java.lang.String sNamespace)
Constructor that consumes the host and port to connect to.

XmppSession(XmlStreamFactory streamFactory, java.lang.String sNamespace)
Constructor that consumes the host and port to connect to.

Method Summary

void	addListener(XmppSessionListener listener) Add an XMPP session listener.
void	addTransformer(org.xml.sax.ContentHandler transformer) Register an XML/XMPP transformer with the stream.
void	close() Close the connection to the Jabber server.
protected void	close(XmppSession.ParserThread parser, XmppSessionListener.Type type, java.lang.String sDetail) Close the connection and signal an error by firing an event.
void	fireEvent(XmppSessionListener.Event event) Fire a session event to each of the session listeners.
java.lang.String	getAttribute(java.lang.String sQName) Provide an attribute from the <stream:stream> top level element.
java.lang.String	getNamespace() Provide the session namespace.
protected org.xml.sax.ContentHandler[]	getTransformers() Provide the transformer list as an array of ContentHandlers.
boolean	isOpen() Determine if the connection is open and the top level stream element has been received.
void	open() This method opens a connection to the Jabber server.
boolean	removeListener(XmppSessionListener listener) Remove a session listener.
boolean	removeTransformer(org.xml.sax.ContentHandler i) Remove an XML/XMPP transformer from the stream.
void	waitForOpen(long timeout) Block until the session is ready for writing packets.
void	write(java.lang.String sPacket) Write raw XML to the Jabber server.

Methods inherited from class java.lang.Object

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

Field Detail

m_bOpen

protected boolean m_bOpen

Are we open for streaming XMPP packets?

m_openMonitor

protected java.lang.Object m_openMonitor

A monitor for threads to wait on pending the session being opened.

m_saxEventManager

protected SaxEventManager m_saxEventManager

Object to handle SAX events during XMPP processing.

m_currentParserThread

protected XmppSession.ParserThread m_currentParserThread

Our current parser thread. It's possible two may be active when close() and open() are called back to back. In which case the old thread would still be closing as the new one was opening.

m_sNamespace

protected java.lang.String m_sNamespace

The Jabber namespace to use.

m_connection

protected XmlStream m_connection

Our connection to jabber.

m_connectionFactory

protected XmlStreamFactory m_connectionFactory

Our connection factory.

m_out

protected java.io.OutputStream m_out

XML stream to the Jabber server.

COMPONENT_ACCEPT_NAMESPACE

public static final java.lang.String COMPONENT_ACCEPT_NAMESPACE

The Jabber component accept namespace for components initiating communications with a host.

See Also:

Constant Field Values

JABBER_CLIENT_NAMESPACE

public static final java.lang.String JABBER_CLIENT_NAMESPACE

The Jabber client namespace for node to host, and host to node communications.

See Also:

Constant Field Values

JABBER_SERVER_NAMESPACE

public static final java.lang.String JABBER_SERVER_NAMESPACE

The Jabber host to host communications namespace.

See Also:

Constant Field Values

COMPONENT_CONNECT_NAMESPACE

public static final java.lang.String COMPONENT_CONNECT_NAMESPACE

The Jabber component connect namespace, for hosts initiating a connection to a component.

See Also:

Constant Field Values

m_sessionListeners

protected XmppSessionListener[] m_sessionListeners

Session lifecycle listeners. Each element is of type XmppSessionListener.

m_sessionListenerMutex

protected java.lang.Object m_sessionListenerMutex

Mutex to synchronize modifications to the session listener list.

m_transformers

protected java.util.List m_transformers

XML/XMPP transformers. Each element is of type ContentHandler.

DEFAULT_OPEN_TIMEOUT

public static final long DEFAULT_OPEN_TIMEOUT

The default amount of time, in milliseconds, that it should take for the jabber server to respond to the opening XML <stream:stream> element. Default is 30 seconds.

See Also:

Constant Field Values

DEFAULT_PARSER_NAME

protected static final java.lang.String DEFAULT_PARSER_NAME

Default XML parser name.

See Also:

Constant Field Values

Constructor Detail

XmppSession

public XmppSession(XmlStreamFactory streamFactory,
                   java.lang.String sNamespace)

Constructor that consumes the host and port to connect to. Use open() to connect to the Jabber server. After the session is opened you should use an authentication suitable to the selected namespace. Once the session is open, session attributes can be accessed using getAttribute().

Parameters:

streamFactory - An XML stream factory.

sNamespace - The Jabber namespace to use.

XmppSession

public XmppSession(java.lang.String sHost,
                   int nPort,
                   java.lang.String sNamespace)

Constructor that consumes the host and port to connect to. Use open() to connect to the Jabber server. After the session is opened you should use an authentication suitable to the selected namespace. Once the session is open, session attributes can be accessed using getAttribute().

* @param sHost The server name, or IP address (as a dotted quad) to connect to. * @param nPort The port on the Jabber server to connect to.

Parameters:

sNamespace - The Jabber namespace to use.

Method Detail

open

public void open()
          throws java.io.IOException

This method opens a connection to the Jabber server. After calling open(), remember to send the appropriate authentication packets using write().

* @throws IOException

java.io.IOException

close

protected void close(XmppSession.ParserThread parser,
                     XmppSessionListener.Type type,
                     java.lang.String sDetail)

Close the connection and signal an error by firing an event.

Parameters:

parser - The parser thread calling close. If the parser thread is NOT the active one, then only the event will be fired and the current stream will NOT be closed.

sDetail - The detail message for the event.

close

public void close()

Close the connection to the Jabber server.

getNamespace

public java.lang.String getNamespace()

Provide the session namespace.

* @return The session namespace.

getAttribute

public java.lang.String getAttribute(java.lang.String sQName)

Provide an attribute from the <stream:stream> top level element. Typical attributes are id and from.

Parameters:

sQName - The name of the attribute.

Returns:

The value of the attribute,

write

public void write(java.lang.String sPacket)
           throws java.io.IOException

Write raw XML to the Jabber server. Only complete packets should be passed to this method to avoid interleaving fragmented packets from multiple writers. flush() is called automatically for each packet.

* @param sPacket The COMPLETE raw XML packet to write to the Jabber server. * @throws IOException Generated when there are problems writing to the stream.

java.io.IOException

isOpen

public boolean isOpen()

Determine if the connection is open and the top level stream element has been received.

Returns:

True if the connection is open.

addListener

public void addListener(XmppSessionListener listener)

Add an XMPP session listener. Session listeners receive session lifecycle events.

* @param listener The listener to register.

removeListener

public boolean removeListener(XmppSessionListener listener)

Remove a session listener.

* @param listener The listener to remove. * @return True if the listener was removed from the list. False means the listener was not part of the list.

fireEvent

public void fireEvent(XmppSessionListener.Event event)

Fire a session event to each of the session listeners.

* @param event The event to send to each of the session listeners.

addTransformer

public void addTransformer(org.xml.sax.ContentHandler transformer)

Register an XML/XMPP transformer with the stream. Each transformer consumes SAX events to build an in-memory representation of the XMPP packet. Interested parties should register with a transformer.

Note that the transformer will start receiving SAX events at the start of the NEXT XMPP packet. This is to provide a clean event model.

Also note that transformers persist across Jabber sessions. Meaning that connections may get dropped, and then re-established. In this case, each transformed would receive the startDocument() call before new SAX events arrive from the new session. All partially instantiated packets should be dropped when a startDocument() event is received.

* @param transformer The transformer to register.

removeTransformer

public boolean removeTransformer(org.xml.sax.ContentHandler i)

Remove an XML/XMPP transformer from the stream.

* @param transformer The transformer to remove. * @return True if the transformer was removed. False means the transformer was not registered.

getTransformers

protected org.xml.sax.ContentHandler[] getTransformers()

Provide the transformer list as an array of ContentHandlers.

* @return ContentHandler[] The list of transformers as an array of content handlers.

waitForOpen

public void waitForOpen(long timeout)
                 throws java.io.IOException

Block until the session is ready for writing packets.

Parameters:

timeout - The maximum time in milliseconds to wait.

Throws:

java.io.IOException - Generated when the stream did not open in the allotted time.