org.jivesoftware.smackx.bytestreams.ibb

Class InBandBytestreamManager

java.lang.Object

org.jivesoftware.smack.Manager

org.jivesoftware.smackx.bytestreams.ibb.InBandBytestreamManager

All Implemented Interfaces:

BytestreamManager

public final class InBandBytestreamManager
extends Manager
implements BytestreamManager

The InBandBytestreamManager class handles establishing In-Band Bytestreams as specified in the XEP-0047.

The In-Band Bytestreams (IBB) enables two entities to establish a virtual bytestream over which they can exchange Base64-encoded chunks of data over XMPP itself. It is the fall-back mechanism in case the Socks5 bytestream method of transferring data is not available.

There are two ways to send data over an In-Band Bytestream. It could either use IQ stanzas to send data packets or message stanzas. If IQ stanzas are used every data stanza is acknowledged by the receiver. This is the recommended way to avoid possible rate-limiting penalties. Message stanzas are not acknowledged because most XMPP server implementation don't support stanza flow-control method like Advanced Message Processing. To set the stanza that should be used invoke setStanza(StanzaType).

To establish an In-Band Bytestream invoke the establishSession(Jid) method. This will negotiate an in-band bytestream with the given target JID and return a session.

If a session ID for the In-Band Bytestream was already negotiated (e.g. while negotiating a file transfer) invoke establishSession(Jid, String).

To handle incoming In-Band Bytestream requests add an InBandBytestreamListener to the manager. There are two ways to add this listener. If you want to be informed about incoming In-Band Bytestreams from a specific user add the listener by invoking addIncomingBytestreamListener(BytestreamListener, Jid). If the listener should respond to all In-Band Bytestream requests invoke addIncomingBytestreamListener(BytestreamListener).

Note that the registered InBandBytestreamListener will NOT be notified on incoming In-Band bytestream requests sent in the context of XEP-0096 file transfer. (See FileTransferManager)

If no InBandBytestreamListeners are registered, all incoming In-Band bytestream requests will be rejected by returning a <not-acceptable/> error to the initiator.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	InBandBytestreamManager.StanzaType Stanzas that can be used to encapsulate In-Band Bytestream data packets.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAXIMUM_BLOCK_SIZE Maximum block size that is allowed for In-Band Bytestreams.

Method Summary

Modifier and Type	Method and Description
void	addIncomingBytestreamListener(BytestreamListener listener) Adds InBandBytestreamListener that is called for every incoming in-band bytestream request unless there is a user specific InBandBytestreamListener registered.
void	addIncomingBytestreamListener(BytestreamListener listener, Jid initiatorJID) Adds InBandBytestreamListener that is called for every incoming in-band bytestream request from the given user.
InBandBytestreamSession	establishSession(Jid targetJID) Establishes an In-Band Bytestream with the given user and returns the session to send/receive data to/from the user.
InBandBytestreamSession	establishSession(Jid targetJID, String sessionID) Establishes an In-Band Bytestream with the given user using the given session ID and returns the session to send/receive data to/from the user.
protected List<BytestreamListener>	getAllRequestListeners() Returns a list of InBandBytestreamListener that are informed if there are no listeners for a specific initiator.
static InBandBytestreamManager	getByteStreamManager(XMPPConnection connection) Returns the InBandBytestreamManager to handle In-Band Bytestreams for a given XMPPConnection.
protected XMPPConnection	getConnection() Returns the XMPP connection.
int	getDefaultBlockSize() Returns the default block size that is used for all outgoing in-band bytestreams for this connection.
protected List<String>	getIgnoredBytestreamRequests() Returns the list of session IDs that should be ignored by the InitialtionListener
int	getMaximumBlockSize() Returns the maximum block size that is allowed for In-Band Bytestreams for this connection.
protected Map<String,InBandBytestreamSession>	getSessions() Returns the sessions map.
InBandBytestreamManager.StanzaType	getStanza() Returns the stanza used to send data packets.
protected BytestreamListener	getUserListener(Jid initiator) Returns the InBandBytestreamListener that should be informed if a In-Band Bytestream request from the given initiator JID is received.
void	ignoreBytestreamRequestOnce(String sessionID) Use this method to ignore the next incoming In-Band Bytestream request containing the given session ID.
void	removeIncomingBytestreamListener(BytestreamListener listener) Removes the given listener from the list of listeners for all incoming In-Band Bytestream requests.
void	removeIncomingBytestreamListener(Jid initiatorJID) Removes the listener for the given user.
protected void	replyItemNotFoundPacket(IQ request) Responses to the given IQ packet's sender with an XMPP error that an In-Band Bytestream session could not be found.
protected void	replyRejectPacket(IQ request) Responses to the given IQ packet's sender with an XMPP error that an In-Band Bytestream is not accepted.
protected void	replyResourceConstraintPacket(IQ request) Responses to the given IQ packet's sender with an XMPP error that an In-Band Bytestream open request is rejected because its block size is greater than the maximum allowed block size.
void	setDefaultBlockSize(int defaultBlockSize) Sets the default block size that is used for all outgoing in-band bytestreams for this connection.
void	setMaximumBlockSize(int maximumBlockSize) Sets the maximum block size that is allowed for In-Band Bytestreams for this connection.
void	setStanza(InBandBytestreamManager.StanzaType stanza) Sets the stanza used to send data packets.

Methods inherited from class org.jivesoftware.smack.Manager

connection, getAuthenticatedConnectionOrThrow, schedule

Methods inherited from class java.lang.Object

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

Field Detail

MAXIMUM_BLOCK_SIZE

public static final int MAXIMUM_BLOCK_SIZE

Maximum block size that is allowed for In-Band Bytestreams.

See Also:

Constant Field Values

Method Detail

getByteStreamManager

public static InBandBytestreamManager getByteStreamManager(XMPPConnection connection)

Returns the InBandBytestreamManager to handle In-Band Bytestreams for a given XMPPConnection.

Parameters:

connection - the XMPP connection

Returns:

the InBandBytestreamManager for the given XMPP connection

addIncomingBytestreamListener

public void addIncomingBytestreamListener(BytestreamListener listener)

Adds InBandBytestreamListener that is called for every incoming in-band bytestream request unless there is a user specific InBandBytestreamListener registered.

If no listeners are registered all In-Band Bytestream request are rejected with a <not-acceptable/> error.

Note that the registered InBandBytestreamListener will NOT be notified on incoming Socks5 bytestream requests sent in the context of XEP-0096 file transfer. (See FileTransferManager)

Specified by:

addIncomingBytestreamListener in interface BytestreamManager

Parameters:

listener - the listener to register

removeIncomingBytestreamListener

public void removeIncomingBytestreamListener(BytestreamListener listener)

Removes the given listener from the list of listeners for all incoming In-Band Bytestream requests.

Specified by:

removeIncomingBytestreamListener in interface BytestreamManager

Parameters:

listener - the listener to remove

addIncomingBytestreamListener

public void addIncomingBytestreamListener(BytestreamListener listener,
                                          Jid initiatorJID)

Adds InBandBytestreamListener that is called for every incoming in-band bytestream request from the given user.

Use this method if you are awaiting an incoming Socks5 bytestream request from a specific user.

If no listeners are registered all In-Band Bytestream request are rejected with a <not-acceptable/> error.

Note that the registered InBandBytestreamListener will NOT be notified on incoming Socks5 bytestream requests sent in the context of XEP-0096 file transfer. (See FileTransferManager)

Specified by:

addIncomingBytestreamListener in interface BytestreamManager

Parameters:

listener - the listener to register

initiatorJID - the JID of the user that wants to establish an In-Band Bytestream

removeIncomingBytestreamListener

public void removeIncomingBytestreamListener(Jid initiatorJID)

Removes the listener for the given user.

Specified by:

removeIncomingBytestreamListener in interface BytestreamManager

Parameters:

initiatorJID - the JID of the user the listener should be removed

ignoreBytestreamRequestOnce

public void ignoreBytestreamRequestOnce(String sessionID)

Use this method to ignore the next incoming In-Band Bytestream request containing the given session ID. No listeners will be notified for this request and and no error will be returned to the initiator.

This method should be used if you are awaiting an In-Band Bytestream request as a reply to another stanza (e.g. file transfer).

Parameters:

sessionID - to be ignored

getDefaultBlockSize

public int getDefaultBlockSize()

Returns the default block size that is used for all outgoing in-band bytestreams for this connection.

The recommended default block size is 4096 bytes. See XEP-0047 Section 5.

Returns:

the default block size

setDefaultBlockSize

public void setDefaultBlockSize(int defaultBlockSize)

Sets the default block size that is used for all outgoing in-band bytestreams for this connection.

The default block size must be between 1 and 65535 bytes. The recommended default block size is 4096 bytes. See XEP-0047 Section 5.

Parameters:

defaultBlockSize - the default block size to set

getMaximumBlockSize

public int getMaximumBlockSize()

Returns the maximum block size that is allowed for In-Band Bytestreams for this connection.

Incoming In-Band Bytestream open request will be rejected with an <resource-constraint/> error if the block size is greater then the maximum allowed block size.

The default maximum block size is 65535 bytes.

Returns:

the maximum block size

setMaximumBlockSize

public void setMaximumBlockSize(int maximumBlockSize)

Sets the maximum block size that is allowed for In-Band Bytestreams for this connection.

The maximum block size must be between 1 and 65535 bytes.

Incoming In-Band Bytestream open request will be rejected with an <resource-constraint/> error if the block size is greater then the maximum allowed block size.

Parameters:

maximumBlockSize - the maximum block size to set

getStanza

public InBandBytestreamManager.StanzaType getStanza()

Returns the stanza used to send data packets.

Default is InBandBytestreamManager.StanzaType.IQ. See XEP-0047 Section 4.

Returns:

the stanza used to send data packets

setStanza

public void setStanza(InBandBytestreamManager.StanzaType stanza)

Sets the stanza used to send data packets.

The use of InBandBytestreamManager.StanzaType.IQ is recommended. See XEP-0047 Section 4.

Parameters:

stanza - the stanza to set

establishSession

public InBandBytestreamSession establishSession(Jid targetJID)
                                         throws XMPPException,
                                                SmackException,
                                                InterruptedException

Establishes an In-Band Bytestream with the given user and returns the session to send/receive data to/from the user.

Use this method to establish In-Band Bytestreams to users accepting all incoming In-Band Bytestream requests since this method doesn't provide a way to tell the user something about the data to be sent.

To establish an In-Band Bytestream after negotiation the kind of data to be sent (e.g. file transfer) use establishSession(Jid, String).

Specified by:

establishSession in interface BytestreamManager

Parameters:

targetJID - the JID of the user an In-Band Bytestream should be established

Returns:

the session to send/receive data to/from the user

Throws:

XMPPException - if the user doesn't support or accept in-band bytestreams, or if the user prefers smaller block sizes

SmackException - if there was no response from the server.

InterruptedException

establishSession

public InBandBytestreamSession establishSession(Jid targetJID,
                                                String sessionID)
                                         throws SmackException.NoResponseException,
                                                XMPPException.XMPPErrorException,
                                                SmackException.NotConnectedException,
                                                InterruptedException

Establishes an In-Band Bytestream with the given user using the given session ID and returns the session to send/receive data to/from the user.

Specified by:

establishSession in interface BytestreamManager

Parameters:

targetJID - the JID of the user an In-Band Bytestream should be established

sessionID - the session ID for the In-Band Bytestream request

Returns:

the session to send/receive data to/from the user

Throws:

XMPPException.XMPPErrorException - if the user doesn't support or accept in-band bytestreams, or if the user prefers smaller block sizes

SmackException.NoResponseException - if there was no response from the server.

SmackException.NotConnectedException

InterruptedException

replyRejectPacket

protected void replyRejectPacket(IQ request)
                          throws SmackException.NotConnectedException,
                                 InterruptedException

Responses to the given IQ packet's sender with an XMPP error that an In-Band Bytestream is not accepted.

Parameters:

request - IQ stanza that should be answered with a not-acceptable error

Throws:

SmackException.NotConnectedException

InterruptedException

replyResourceConstraintPacket

protected void replyResourceConstraintPacket(IQ request)
                                      throws SmackException.NotConnectedException,
                                             InterruptedException

Responses to the given IQ packet's sender with an XMPP error that an In-Band Bytestream open request is rejected because its block size is greater than the maximum allowed block size.

Parameters:

request - IQ stanza that should be answered with a resource-constraint error

Throws:

SmackException.NotConnectedException

InterruptedException

replyItemNotFoundPacket

protected void replyItemNotFoundPacket(IQ request)
                                throws SmackException.NotConnectedException,
                                       InterruptedException

Responses to the given IQ packet's sender with an XMPP error that an In-Band Bytestream session could not be found.

Parameters:

request - IQ stanza that should be answered with a item-not-found error

Throws:

SmackException.NotConnectedException

InterruptedException

getConnection

protected XMPPConnection getConnection()

Returns the XMPP connection.

Returns:

the XMPP connection

getUserListener

protected BytestreamListener getUserListener(Jid initiator)

Returns the InBandBytestreamListener that should be informed if a In-Band Bytestream request from the given initiator JID is received.

Parameters:

initiator - the initiator's JID

Returns:

the listener

getAllRequestListeners

protected List<BytestreamListener> getAllRequestListeners()

Returns a list of InBandBytestreamListener that are informed if there are no listeners for a specific initiator.

Returns:

list of listeners

getSessions

protected Map<String,InBandBytestreamSession> getSessions()

Returns the sessions map.

Returns:

the sessions map

getIgnoredBytestreamRequests

protected List<String> getIgnoredBytestreamRequests()

Returns the list of session IDs that should be ignored by the InitialtionListener

Returns:

list of session IDs