org.jivesoftware.whack
Class ExternalComponentManager

java.lang.Object
  org.jivesoftware.whack.ExternalComponentManager

All Implemented Interfaces:

org.xmpp.component.ComponentManager

public class ExternalComponentManager
extends Object
implements org.xmpp.component.ComponentManager

Implementation of the ComponentManager interface for external components. This implementation follows JEP-0014.

Author:

Matt Tucker

Constructor Summary

ExternalComponentManager(String host)
Constructs a new ExternalComponentManager that will make connections to the specified XMPP server on the default port (5222).

ExternalComponentManager(String host, int port)
Constructs a new ExternalComponentManager that will make connections to the specified XMPP server on the given port.

Method Summary

void	addComponent(String subdomain, org.xmpp.component.Component component) Adds a component.
void	addComponent(String subdomain, org.xmpp.component.Component component, Integer port)
int	getConnectTimeout() Returns the timeout (in milliseconds) to use when trying to connect to the server.
org.xmpp.component.Log	getLog() Returns a Log instance, which can be used by components for logging error, warning, info, and debug messages.
String	getProperty(String name) Returns a property value specified by name.
String	getSecretKey(String subdomain) Returns the secret key for a sub-domain.
String	getServerName() Returns the domain of the XMPP server where we are connected to or null if this value was never configured.
boolean	isExternalMode() Returns true if components managed by this component manager are external components connected to the server over a network connection.
boolean	isMultipleAllowed(String subdomain) Returns if we want components to be able to connect multiple times to the same JID.
void	query(org.xmpp.component.Component component, org.xmpp.packet.IQ packet, IQResultListener listener) Sends an IQ packet to the server and returns immediately.
org.xmpp.packet.IQ	query(org.xmpp.component.Component component, org.xmpp.packet.IQ packet, long timeout) Sends an IQ packet to the XMPP server and waits to get an IQ of type result or error.
void	removeComponent(String subdomain) Removes a component.
void	sendPacket(org.xmpp.component.Component component, org.xmpp.packet.Packet packet) Sends a packet to the XMPP server.
void	setConnectTimeout(int connectTimeout) Sets the timeout (in milliseconds) to use when trying to connect to the server.
void	setDefaultSecretKey(String secretKey) Sets the default secret key, which will be used when connecting if a specific secret key for the component hasn't been sent.
void	setMultipleAllowed(String subdomain, boolean allowMultiple) Sets whether we will tell the XMPP server that we want multiple components to be able to connect to the same JID.
void	setProperty(String name, String value) Sets a property value.
void	setSecretKey(String subdomain, String secretKey) Sets a secret key for a sub-domain, for future use by a component connecting to the server.
void	setServerName(String domain) Sets the domain of the XMPP server.

Methods inherited from class java.lang.Object

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

Constructor Detail

ExternalComponentManager

public ExternalComponentManager(String host)

Constructs a new ExternalComponentManager that will make connections to the specified XMPP server on the default port (5222).

Parameters:

host - the IP address or name of the XMPP server to connect to (e.g. "example.com").

ExternalComponentManager

public ExternalComponentManager(String host,
                                int port)

Constructs a new ExternalComponentManager that will make connections to the specified XMPP server on the given port.

Parameters:

host - the IP address or name of the XMPP server to connect to (e.g. "example.com").

port - the port to connect on.

Method Detail

setSecretKey

public void setSecretKey(String subdomain,
                         String secretKey)

Sets a secret key for a sub-domain, for future use by a component connecting to the server. Keys are used as an authentication mechanism when connecting to the server. Some servers may require a different key for each component, while others may use a global secret key.

Parameters:

subdomain - the sub-domain.

secretKey - the secret key

getSecretKey

public String getSecretKey(String subdomain)

Returns the secret key for a sub-domain. If no key was found then the default secret key will be returned.

Parameters:

subdomain - the subdomain to return its secret key.

Returns:

the secret key for a sub-domain.

setDefaultSecretKey

public void setDefaultSecretKey(String secretKey)

Sets the default secret key, which will be used when connecting if a specific secret key for the component hasn't been sent. Keys are used as an authentication mechanism when connecting to the server. Some servers may require a different key for each component, while others may use a global secret key.

Parameters:

secretKey - the default secret key.

isMultipleAllowed

public boolean isMultipleAllowed(String subdomain)

Returns if we want components to be able to connect multiple times to the same JID. This is a custom Openfire extension and will not work with any other XMPP server. Other XMPP servers should ignore this extra setting.

Parameters:

subdomain - the sub-domain.

Returns:

True or false if we are allowing multiple connections.

setMultipleAllowed

public void setMultipleAllowed(String subdomain,
                               boolean allowMultiple)

Sets whether we will tell the XMPP server that we want multiple components to be able to connect to the same JID. This is a custom Openfire extension and will not work with any other XMPP server. Other XMPP servers should ignore this extra setting.

Parameters:

subdomain - the sub-domain.

allowMultiple - Set to true if we want to allow multiple connections to same JID.

addComponent

public void addComponent(String subdomain,
                         org.xmpp.component.Component component)
                  throws org.xmpp.component.ComponentException

Description copied from interface: org.xmpp.component.ComponentManager

Adds a component. The Component.initialize(org.xmpp.packet.JID, ComponentManager) method will be called on the component. The subdomain specifies the address of the component on a server. For example, if the subdomain is "test" and the XMPP server is at "example.com", then the component's address would be "test.example.com".

Specified by:

addComponent in interface org.xmpp.component.ComponentManager

Parameters:

subdomain - the subdomain of the component's address.

component - the component.

Throws:

org.xmpp.component.ComponentException - if the component connection is lost and the component cannot be added.

addComponent

public void addComponent(String subdomain,
                         org.xmpp.component.Component component,
                         Integer port)
                  throws org.xmpp.component.ComponentException

Throws:

org.xmpp.component.ComponentException

removeComponent

public void removeComponent(String subdomain)
                     throws org.xmpp.component.ComponentException

Description copied from interface: org.xmpp.component.ComponentManager

Removes a component. The Component.shutdown() method will be called on the component.

Specified by:

removeComponent in interface org.xmpp.component.ComponentManager

Parameters:

subdomain - the subdomain of the component's address.

Throws:

org.xmpp.component.ComponentException - if the component connection is lost and the component cannot be removed.

sendPacket

public void sendPacket(org.xmpp.component.Component component,
                       org.xmpp.packet.Packet packet)

Description copied from interface: org.xmpp.component.ComponentManager

Sends a packet to the XMPP server. The "from" value of the packet must not be null. An IllegalArgumentException will be thrown when the "from" value is null.

Components are trusted by the server and may use any value in from address. Usually the from address uses the component's address as the domain but this is not required.

Specified by:

sendPacket in interface org.xmpp.component.ComponentManager

Parameters:

component - the component sending the packet.

packet - the packet to send.

query

public org.xmpp.packet.IQ query(org.xmpp.component.Component component,
                                org.xmpp.packet.IQ packet,
                                long timeout)
                         throws org.xmpp.component.ComponentException

Description copied from interface: org.xmpp.component.ComponentManager

Sends an IQ packet to the XMPP server and waits to get an IQ of type result or error. The "from" value of the packet must not be null. An IllegalArgumentException will be thrown when the "from" value is null.

If no answer is received from the server before the specified timeout then null will be returned. Components are trusted by the server and may use any value in from address. Usually the from address uses the component's address as the domain but this is not required.

Specified by:

query in interface org.xmpp.component.ComponentManager

Parameters:

component - the component sending the packet.

packet - the IQ packet to send.

timeout - the number of milliseconds to wait before returning an IQ error.

Returns:

the answer sent by the server. The answer could be an IQ of type result or error. null will be returned if there is no response from the server.

Throws:

org.xmpp.component.ComponentException - if the component connection is lost or unavialble during the time of sending and recieving packets.

query

public void query(org.xmpp.component.Component component,
                  org.xmpp.packet.IQ packet,
                  IQResultListener listener)
           throws org.xmpp.component.ComponentException

Description copied from interface: org.xmpp.component.ComponentManager

Sends an IQ packet to the server and returns immediately. The specified IQResultListener will be invoked when an answer is received.

Specified by:

query in interface org.xmpp.component.ComponentManager

Parameters:

component - the component sending the packet.

packet - the IQ packet to send.

listener - the listener that will be invoked when an answer is received.

Throws:

org.xmpp.component.ComponentException - if the component connection is lost or unavialble during the time of sending and recieving packets.

getProperty

public String getProperty(String name)

Description copied from interface: org.xmpp.component.ComponentManager

Returns a property value specified by name. Properties can be used by components to store configuration data. It is recommended that each component qualify property names to prevent overlap. For example a component that broadcasts messages to groups of users, might prepend all property names it uses with "broadcast.".

Specified by:

getProperty in interface org.xmpp.component.ComponentManager

Parameters:

name - the property name.

Returns:

the property value.

setProperty

public void setProperty(String name,
                        String value)

Description copied from interface: org.xmpp.component.ComponentManager

Sets a property value. Properties can be used by components to store configuration data. It is recommended that each component qualify property names to prevent overlap. For example a component that broadcasts messages to groups of users, might prepend all property names it uses with "broadcast.".

Specified by:

setProperty in interface org.xmpp.component.ComponentManager

Parameters:

name - the property name.

value - the property value.

setServerName

public void setServerName(String domain)

Sets the domain of the XMPP server. The domain may or may not match the host. The domain will be used mainly for the XMPP packets while the host is used mainly for creating connections to the server.

Parameters:

domain - the domain of the XMPP server.

getServerName

public String getServerName()

Returns the domain of the XMPP server where we are connected to or null if this value was never configured. When the value is null then the component will register with just its subdomain and we expect the server to accept the component and append its domain to form the JID of the component.

Specified by:

getServerName in interface org.xmpp.component.ComponentManager

Returns:

the domain of the XMPP server or null if never configured.

getConnectTimeout

public int getConnectTimeout()

Returns the timeout (in milliseconds) to use when trying to connect to the server. The default value is 2 seconds.

Returns:

the timeout to use when trying to connect to the server.

setConnectTimeout

public void setConnectTimeout(int connectTimeout)

Sets the timeout (in milliseconds) to use when trying to connect to the server. The default value is 2 seconds.

Parameters:

connectTimeout - the timeout, in milliseconds, to use when trying to connect to the server.

isExternalMode

public boolean isExternalMode()

Description copied from interface: org.xmpp.component.ComponentManager

Returns true if components managed by this component manager are external components connected to the server over a network connection. Otherwise, the components are internal to the server.

Specified by:

isExternalMode in interface org.xmpp.component.ComponentManager

Returns:

true if the managed components are external components.

getLog

public org.xmpp.component.Log getLog()

Description copied from interface: org.xmpp.component.ComponentManager

Returns a Log instance, which can be used by components for logging error, warning, info, and debug messages.

Specified by:

getLog in interface org.xmpp.component.ComponentManager

Returns:

a Log instance.