org.jivesoftware.smackx.bytestreams.ibb
Class InBandBytestreamManager

java.lang.Object
  org.jivesoftware.smackx.bytestreams.ibb.InBandBytestreamManager

All Implemented Interfaces:

BytestreamManager

public class InBandBytestreamManager
extends Object
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 packet 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(String) 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(String, 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, String). 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.

Author:

Henning Staib

Nested Class Summary

static class

InBandBytestreamManager.StanzaType Stanzas that can be used to encapsulate In-Band Bytestream data packets.

Field Summary

static int	MAXIMUM_BLOCK_SIZE Maximum block size that is allowed for In-Band Bytestreams
static String	NAMESPACE The XMPP namespace of the In-Band Bytestream

Method Summary

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, String initiatorJID) Adds InBandBytestreamListener that is called for every incoming in-band bytestream request from the given user.
InBandBytestreamSession	establishSession(String targetJID) Establishes an In-Band Bytestream with the given user and returns the session to send/receive data to/from the user.
InBandBytestreamSession	establishSession(String 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(Connection connection) Returns the InBandBytestreamManager to handle In-Band Bytestreams for a given Connection.
protected Connection	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(String 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(String 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 java.lang.Object

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

Field Detail

NAMESPACE

public static final String NAMESPACE

The XMPP namespace of the In-Band Bytestream

See Also:

Constant Field Values

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(Connection connection)

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

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,
                                          String 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(String 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 packet (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(String targetJID)
                                         throws XMPPException

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(String, 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

establishSession

public InBandBytestreamSession establishSession(String targetJID,
                                                String sessionID)
                                         throws XMPPException

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 - if the user doesn't support or accept in-band bytestreams, or if the user prefers smaller block sizes

replyRejectPacket

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.

Parameters:

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

replyResourceConstraintPacket

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.

Parameters:

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

replyItemNotFoundPacket

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.

Parameters:

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

getConnection

protected Connection getConnection()

Returns the XMPP connection.

Returns:

the XMPP connection

getUserListener

protected BytestreamListener getUserListener(String 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