Smack

org.jivesoftware.smackx.bytestreams.socks5
Class Socks5BytestreamManager

java.lang.Object
  extended by org.jivesoftware.smackx.bytestreams.socks5.Socks5BytestreamManager
All Implemented Interfaces:
BytestreamManager

public final class Socks5BytestreamManager
extends Object
implements BytestreamManager

The Socks5BytestreamManager class handles establishing SOCKS5 Bytestreams as specified in the XEP-0065.

A SOCKS5 Bytestream is negotiated partly over the XMPP XML stream and partly over a separate socket. The actual transfer though takes place over a separately created socket.

A SOCKS5 Bytestream generally has three parties, the initiator, the target, and the stream host. The stream host is a specialized SOCKS5 proxy setup on a server, or, the initiator can act as the stream host.

To establish a SOCKS5 Bytestream invoke the establishSession(String) method. This will negotiate a SOCKS5 Bytestream with the given target JID and return a socket.

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

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

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

If no Socks5BytestreamListeners are registered, all incoming SOCKS5 Bytestream requests will be rejected by returning a <not-acceptable/> error to the initiator.

Author:
Henning Staib

Field Summary
static String NAMESPACE
          The XMPP namespace of the SOCKS5 Bytestream
 
Method Summary
 void addIncomingBytestreamListener(BytestreamListener listener)
          Adds BytestreamListener that is called for every incoming SOCKS5 Bytestream request unless there is a user specific BytestreamListener registered.
 void addIncomingBytestreamListener(BytestreamListener listener, String initiatorJID)
          Adds BytestreamListener that is called for every incoming SOCKS5 Bytestream request from the given user.
 void disableService()
          Disables the SOCKS5 Bytestream manager by removing the SOCKS5 Bytestream feature from the service discovery, disabling the listener for SOCKS5 Bytestream initiation requests and resetting its internal state.
 Socks5BytestreamSession establishSession(String targetJID)
          Establishes a SOCKS5 Bytestream with the given user and returns the Socket to send/receive data to/from the user.
 Socks5BytestreamSession establishSession(String targetJID, String sessionID)
          Establishes a SOCKS5 Bytestream with the given user using the given session ID and returns the Socket to send/receive data to/from the user.
protected  List<BytestreamListener> getAllRequestListeners()
          Returns a list of BytestreamListener that are informed if there are no listeners for a specific initiator.
static Socks5BytestreamManager getBytestreamManager(Connection connection)
          Returns the Socks5BytestreamManager to handle SOCKS5 Bytestreams for a given Connection.
protected  Connection getConnection()
          Returns the XMPP connection.
protected  List<String> getIgnoredBytestreamRequests()
          Returns the list of session IDs that should be ignored by the InitialtionListener
 int getProxyConnectionTimeout()
          Returns the timeout for connecting to the SOCKS5 proxy selected by the target.
 int getTargetResponseTimeout()
          Returns the timeout to wait for the response to the SOCKS5 Bytestream initialization request.
protected  BytestreamListener getUserListener(String initiator)
          Returns the BytestreamListener that should be informed if a SOCKS5 Bytestream request from the given initiator JID is received.
 void ignoreBytestreamRequestOnce(String sessionID)
          Use this method to ignore the next incoming SOCKS5 Bytestream request containing the given session ID.
 boolean isProxyPrioritizationEnabled()
          Returns if the prioritization of the last working SOCKS5 proxy on successive SOCKS5 Bytestream connections is enabled.
 void removeIncomingBytestreamListener(BytestreamListener listener)
          Removes the given listener from the list of listeners for all incoming SOCKS5 Bytestream requests.
 void removeIncomingBytestreamListener(String initiatorJID)
          Removes the listener for the given user.
protected  void replyRejectPacket(IQ packet)
          Responses to the given packet's sender with a XMPP error that a SOCKS5 Bytestream is not accepted.
 void setProxyConnectionTimeout(int proxyConnectionTimeout)
          Sets the timeout for connecting to the SOCKS5 proxy selected by the target.
 void setProxyPrioritizationEnabled(boolean proxyPrioritizationEnabled)
          Enable/disable the prioritization of the last working SOCKS5 proxy on successive SOCKS5 Bytestream connections.
 void setTargetResponseTimeout(int targetResponseTimeout)
          Sets the timeout to wait for the response to the SOCKS5 Bytestream initialization request.
 
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 SOCKS5 Bytestream

See Also:
Constant Field Values
Method Detail

getBytestreamManager

public static Socks5BytestreamManager getBytestreamManager(Connection connection)
Returns the Socks5BytestreamManager to handle SOCKS5 Bytestreams for a given Connection.

If no manager exists a new is created and initialized.

Parameters:
connection - the XMPP connection or null if given connection is null
Returns:
the Socks5BytestreamManager for the given XMPP connection

addIncomingBytestreamListener

public void addIncomingBytestreamListener(BytestreamListener listener)
Adds BytestreamListener that is called for every incoming SOCKS5 Bytestream request unless there is a user specific BytestreamListener registered.

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

Note that the registered BytestreamListener 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 SOCKS5 Bytestream requests.

Specified by:
removeIncomingBytestreamListener in interface BytestreamManager
Parameters:
listener - the listener to remove

addIncomingBytestreamListener

public void addIncomingBytestreamListener(BytestreamListener listener,
                                          String initiatorJID)
Adds BytestreamListener that is called for every incoming SOCKS5 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 SOCKS5 Bytestream request are rejected with a <not-acceptable/> error.

Note that the registered BytestreamListener 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 a SOCKS5 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 SOCKS5 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 a SOCKS5 Bytestream request as a reply to another packet (e.g. file transfer).

Parameters:
sessionID - to be ignored

disableService

public void disableService()
Disables the SOCKS5 Bytestream manager by removing the SOCKS5 Bytestream feature from the service discovery, disabling the listener for SOCKS5 Bytestream initiation requests and resetting its internal state.

To re-enable the SOCKS5 Bytestream feature invoke getBytestreamManager(Connection). Using the file transfer API will automatically re-enable the SOCKS5 Bytestream feature.


getTargetResponseTimeout

public int getTargetResponseTimeout()
Returns the timeout to wait for the response to the SOCKS5 Bytestream initialization request. Default is 10000ms.

Returns:
the timeout to wait for the response to the SOCKS5 Bytestream initialization request

setTargetResponseTimeout

public void setTargetResponseTimeout(int targetResponseTimeout)
Sets the timeout to wait for the response to the SOCKS5 Bytestream initialization request. Default is 10000ms.

Parameters:
targetResponseTimeout - the timeout to set

getProxyConnectionTimeout

public int getProxyConnectionTimeout()
Returns the timeout for connecting to the SOCKS5 proxy selected by the target. Default is 10000ms.

Returns:
the timeout for connecting to the SOCKS5 proxy selected by the target

setProxyConnectionTimeout

public void setProxyConnectionTimeout(int proxyConnectionTimeout)
Sets the timeout for connecting to the SOCKS5 proxy selected by the target. Default is 10000ms.

Parameters:
proxyConnectionTimeout - the timeout to set

isProxyPrioritizationEnabled

public boolean isProxyPrioritizationEnabled()
Returns if the prioritization of the last working SOCKS5 proxy on successive SOCKS5 Bytestream connections is enabled. Default is true.

Returns:
true if prioritization is enabled, false otherwise

setProxyPrioritizationEnabled

public void setProxyPrioritizationEnabled(boolean proxyPrioritizationEnabled)
Enable/disable the prioritization of the last working SOCKS5 proxy on successive SOCKS5 Bytestream connections.

Parameters:
proxyPrioritizationEnabled - enable/disable the prioritization of the last working SOCKS5 proxy

establishSession

public Socks5BytestreamSession establishSession(String targetJID)
                                         throws XMPPException,
                                                IOException,
                                                InterruptedException
Establishes a SOCKS5 Bytestream with the given user and returns the Socket to send/receive data to/from the user.

Use this method to establish SOCKS5 Bytestreams to users accepting all incoming Socks5 bytestream requests since this method doesn't provide a way to tell the user something about the data to be sent.

To establish a SOCKS5 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 a SOCKS5 Bytestream should be established
Returns:
the Socket to send/receive data to/from the user
Throws:
XMPPException - if the user doesn't support or accept SOCKS5 Bytestreams, if no Socks5 Proxy could be found, if the user couldn't connect to any of the SOCKS5 Proxies
IOException - if the bytestream could not be established
InterruptedException - if the current thread was interrupted while waiting

establishSession

public Socks5BytestreamSession establishSession(String targetJID,
                                                String sessionID)
                                         throws XMPPException,
                                                IOException,
                                                InterruptedException
Establishes a SOCKS5 Bytestream with the given user using the given session ID and returns the Socket to send/receive data to/from the user.

Specified by:
establishSession in interface BytestreamManager
Parameters:
targetJID - the JID of the user a SOCKS5 Bytestream should be established
sessionID - the session ID for the SOCKS5 Bytestream request
Returns:
the Socket to send/receive data to/from the user
Throws:
XMPPException - if the user doesn't support or accept SOCKS5 Bytestreams, if no Socks5 Proxy could be found, if the user couldn't connect to any of the SOCKS5 Proxies
IOException - if the bytestream could not be established
InterruptedException - if the current thread was interrupted while waiting

replyRejectPacket

protected void replyRejectPacket(IQ packet)
Responses to the given packet's sender with a XMPP error that a SOCKS5 Bytestream is not accepted.

Parameters:
packet - Packet that should be answered with a not-acceptable error

getConnection

protected Connection getConnection()
Returns the XMPP connection.

Returns:
the XMPP connection

getUserListener

protected BytestreamListener getUserListener(String initiator)
Returns the BytestreamListener that should be informed if a SOCKS5 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 BytestreamListener that are informed if there are no listeners for a specific initiator.

Returns:
list of listeners

getIgnoredBytestreamRequests

protected List<String> getIgnoredBytestreamRequests()
Returns the list of session IDs that should be ignored by the InitialtionListener

Returns:
list of session IDs

Smack

Copyright © 2003-2007 Jive Software.