org.xmpp.component
Class AbstractComponent

java.lang.Object
  org.xmpp.component.AbstractComponent

All Implemented Interfaces:

Component

public abstract class AbstractComponent
extends java.lang.Object
implements Component

This class provides a default Component implementation. Most of the default functionality can be overridden by overriding specific methods.

These XMPP features are implemented in the abstract component:

• Service Discovery (XEP-0030)
• XMPP Ping (XEP-0199)
• Last Activity (XEP-0012)
• Entity Time(XEP-0202)

This implementation uses the producer/consumer pattern, in which it takes the role of a consumer of stanzas. Every abstract component has a dedicated thread pool to process stanzas. This pool will use up to the configured maximum amount of threads to process stanzas that are sent to this component. If more stanzas are to be processed simultaneously, they will be placed in a queue (of configurable size) until a thread becomes available again. If the queue is full, the stanza will be dropped and an exception will be logged. If the stanza was an IQ request stanza, an IQ error stanza (internal-server-error/wait) will be returned.

By default, instances of this class are guaranteed to return an IQ response on every consumed IQ of the get or set type, as required by the XMPP specification. If the abstract component cannot formulate a valid response and the extending implementation does not provide a response either (by returning null on invocations of handleIQGet(IQ) and handleIQSet(IQ)) an IQ error response is returned.

The behavior described above can be disabled by setting a corresponding flag in one of the constructors. If an instance is configured in such a way, null responses provided by the extending implementation are not translated in an IQ error. This allows the extending implementation to respond to IQ requests in an asynchrous manner. It will be up to the extending implementation to ensure that every IQ request is responded to.

Note that instances of this class can be used to implement internal (e.g. Openfire plugins) as well as external components.

Author:

Guus der Kinderen, guus.der.kinderen@gmail.com

Field Summary

protected ComponentManager	compMan The component manager to which this Component has been registered.
protected JID	jid The JID of the component, set after registration with a Component manager.
protected org.slf4j.Logger	log The object that's responsible for logging.
static java.lang.String	NAMESPACE_DISCO_INFO The XMPP 'service discovery info' namespace.
static java.lang.String	NAMESPACE_DISCO_ITEMS The XMPP 'service discovery items' namespace.
static java.lang.String	NAMESPACE_ENTITY_TIME The 'Entity Time' namespace
static java.lang.String	NAMESPACE_LAST_ACTIVITY The 'Last Activity' namespace
static java.lang.String	NAMESPACE_XMPP_PING The 'XMPP Ping' namespace

Constructor Summary

AbstractComponent()
Instantiates a new AbstractComponent with a maximum thread pool size of 17 and a maximum queue size of 1000.

AbstractComponent(int maxThreadpoolSize, int maxQueueSize, boolean enforceIQResult)
Instantiates a new AbstractComponent.

Method Summary

protected java.lang.String[]	discoInfoFeatureNamespaces() This method returns a String array that should contain all namespaces of features that this component offers.
protected java.lang.String	discoInfoIdentityCategory() Returns the category of the Service Discovery Identity of this component (this implementation will only hold exactly one Identity for the component).
protected java.lang.String	discoInfoIdentityCategoryType() Returns the type of the Service Discovery Identity of this component (this implementation will only hold exactly one Identity for the component).
abstract java.lang.String	getDescription() Returns the description of this component.
java.lang.String	getDomain() Returns the XMPP domain to which this component is registered to.
JID	getJID() Returns the XMPP address / Jabber ID (JID) of this component.
abstract java.lang.String	getName() Returns the name of this component.
protected IQ	handleDiscoInfo(IQ iq) Default handler of Service Discovery Info requests.
protected IQ	handleDiscoItems(IQ iq) Default handler of Service Discovery Info requests.
protected IQ	handleEntityTime(IQ iq) Default handler of Entity Time requests (XEP-0202).
protected void	handleIQError(IQ iq) Override this method to handle the IQ stanzas of type error that are received by the component.
protected IQ	handleIQGet(IQ iq) Override this method to handle the IQ stanzas of type get that could not be processed by the AbstractComponent implementation.
protected void	handleIQResult(IQ iq) Override this method to handle the IQ stanzas of type result that are received by the component.
protected IQ	handleIQSet(IQ iq) Override this method to handle the IQ stanzas of type set that could not be processed by the AbstractComponent implementation.
protected IQ	handleLastActivity(IQ iq) Default handler of Last Activity requests (XEP-0012).
protected void	handleMessage(Message message) Override this method to handle the Message stanzas that are received by the component.
protected IQ	handlePing(IQ iq) Default handler of Ping requests (XEP-0199).
protected void	handlePresence(Presence presence) Override this method to handle the Presence stanzas that are received by the component.
void	initialize(JID jid, ComponentManager componentManager) Initialize the abstract component.
void	postComponentShutdown() This method gets called as part of the Component shutdown routine.
void	postComponentStart() This method gets called as part of the Component 'start' routine.
void	preComponentShutdown() This method gets called as part of the Component shutdown routine.
void	preComponentStart() This method gets called as part of the Component 'start' routine.
void	processPacket(Packet packet) Processes a packet sent to this Component.
protected void	send(Packet packet) Helper method to send packets.
boolean	servesLocalUsersOnly() Checks if the component can only be used by users of the XMPP domain that the component has registered to.
void	shutdown() Default implementation of the shutdown() method of the Component interface.
void	start() Default implementation of the start() method of the Component interface.

Methods inherited from class java.lang.Object

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

Field Detail

log

protected final org.slf4j.Logger log

The object that's responsible for logging.

NAMESPACE_DISCO_ITEMS

public static final java.lang.String NAMESPACE_DISCO_ITEMS

The XMPP 'service discovery items' namespace.

See Also:

XEP-0030, Constant Field Values

NAMESPACE_DISCO_INFO

public static final java.lang.String NAMESPACE_DISCO_INFO

The XMPP 'service discovery info' namespace.

See Also:

XEP-0030, Constant Field Values

NAMESPACE_XMPP_PING

public static final java.lang.String NAMESPACE_XMPP_PING

The 'XMPP Ping' namespace

See Also:

XEP-0199, Constant Field Values

NAMESPACE_LAST_ACTIVITY

public static final java.lang.String NAMESPACE_LAST_ACTIVITY

The 'Last Activity' namespace

See Also:

XEP-0012, Constant Field Values

NAMESPACE_ENTITY_TIME

public static final java.lang.String NAMESPACE_ENTITY_TIME

The 'Entity Time' namespace

See Also:

XEP-0202, Constant Field Values

compMan

protected ComponentManager compMan

The component manager to which this Component has been registered.

jid

protected JID jid

The JID of the component, set after registration with a Component manager.

Constructor Detail

AbstractComponent

public AbstractComponent()

Instantiates a new AbstractComponent with a maximum thread pool size of 17 and a maximum queue size of 1000.

AbstractComponent

public AbstractComponent(int maxThreadpoolSize,
                         int maxQueueSize,
                         boolean enforceIQResult)

Instantiates a new AbstractComponent.

Parameters:

maxThreadpoolSize - the maximum number of threads that will process work for this component.

maxQueueSize - capacity of the queue that holds tasks that are to be executed by the thread pool.

enforceIQResult - if true, the component will make sure that every request that is received is answered, as specified by the XMPP specification.

Method Detail

initialize

public final void initialize(JID jid,
                             ComponentManager componentManager)
                      throws ComponentException

Initialize the abstract component.

Specified by:

initialize in interface Component

Parameters:

jid - the XMPP address that this component is available at.

componentManager - the component manager.

Throws:

ComponentException - if an error occured while initializing the component.

See Also:

Component.initialize(org.xmpp.packet.JID, org.xmpp.component.ComponentManager)

processPacket

public final void processPacket(Packet packet)

Description copied from interface: Component

Processes a packet sent to this Component.

Specified by:

processPacket in interface Component

Parameters:

packet - the packet.

See Also:

Component.processPacket(org.xmpp.packet.Packet)

handleIQResult

protected void handleIQResult(IQ iq)

Override this method to handle the IQ stanzas of type result that are received by the component. If you do not override this method, the stanzas are ignored.

Parameters:

iq - The IQ stanza of type result that was received by this component.

handleIQError

protected void handleIQError(IQ iq)

Override this method to handle the IQ stanzas of type error that are received by the component. If you do not override this method, the stanzas are ignored.

Parameters:

iq - The IQ stanza of type error that was received by this component.

handleIQGet

protected IQ handleIQGet(IQ iq)
                  throws java.lang.Exception

Override this method to handle the IQ stanzas of type get that could not be processed by the AbstractComponent implementation.

Note that, as any IQ stanza of type get must be replied to, returning null from this method equals returning an IQ error stanza of type 'feature-not-implemented' (this behavior can be disabled by setting the enforceIQResult argument in the constructor to false).

Note that if this method throws an Exception, an IQ stanza of type error, condition 'internal-server-error' will be returned to the sender of the original request.

The default implementation of this method returns null. It is expected that most child classes will override this method.

Parameters:

iq - The IQ request stanza of type get that was received by this component.

Returns:

the response the to request stanza, or null to indicate 'feature-not-available'.

Throws:

java.lang.Exception

handleIQSet

protected IQ handleIQSet(IQ iq)
                  throws java.lang.Exception

Override this method to handle the IQ stanzas of type set that could not be processed by the AbstractComponent implementation.

Note that, as any IQ stanza of type set must be replied to, returning null from this method equals returning an IQ error stanza of type 'feature-not-implemented' {this behavior can be disabled by setting the enforceIQResult argument in the constructor to false).

Note that if this method throws an Exception, an IQ stanza of type error, condition 'internal-server-error' will be returned to the sender of the original request.

The default implementation of this method returns null. It is expected that most child classes will override this method.

Parameters:

iq - The IQ request stanza of type set that was received by this component.

Returns:

the response the to request stanza, or null to indicate 'feature-not-available'.

Throws:

java.lang.Exception

handleDiscoItems

protected IQ handleDiscoItems(IQ iq)

Default handler of Service Discovery Info requests. Unless overridden, this method returns null, which will result into a 'service-unavailable' response to be returned as a response to the original request.

Parameters:

iq - The Service Discovery Items

Returns:

Service Discovery Items response.

handleDiscoInfo

protected IQ handleDiscoInfo(IQ iq)

Default handler of Service Discovery Info requests. Unless overridden, this method returns an IQ result packet that includes:

• One Service Discovery 'Identity'. The attributes of the identity are determined in this way:
  • attribute 'category' : the return value of discoInfoIdentityCategory();
  • attribute 'type' : the return value of discoInfoIdentityCategoryType();
  • attribute 'name' : the name of the entity, as returned by getName() method of the Component interface (which this class implements).
• A list of Service Discovery 'Features', which consist of the 'Service Discovery Info' feature, and the results of discoInfoFeatureNamespaces().

Note that you should include the 'Service Discovery Items' feature if handleDiscoInfo(IQ) returns a non-null value.

Parameters:

iq - The Service Discovery 'info' request stanza.

Returns:

A response to the received Service Discovery 'info' request.

handlePing

protected IQ handlePing(IQ iq)

Default handler of Ping requests (XEP-0199). Unless overridden, this method returns an empty result stanza, which is the expected response to a Ping.

Parameters:

iq - The Ping request stanza.

Returns:

The XMPP way of saying 'pong'.

handleLastActivity

protected IQ handleLastActivity(IQ iq)

Default handler of Last Activity requests (XEP-0012). Unless overridden, this method returns a result stanza that specifies how long this component has been running since it was last (re)started.

Parameters:

iq - The Last Activity request stanza.

Returns:

Last Activity response that reports back the uptime of this component.

handleEntityTime

protected IQ handleEntityTime(IQ iq)

Default handler of Entity Time requests (XEP-0202). Unless overridden, this method returns the current local time as specified by the XEP.

Parameters:

iq - Entity Time request stanza.

Returns:

Result stanza including the local current time.

getDescription

public abstract java.lang.String getDescription()

Description copied from interface: Component

Returns the description of this component.

Specified by:

getDescription in interface Component

Returns:

the description of this component.

getName

public abstract java.lang.String getName()

Description copied from interface: Component

Returns the name of this component.

Specified by:

getName in interface Component

Returns:

the name of this component.

getDomain

public java.lang.String getDomain()

Returns the XMPP domain to which this component is registered to. To full address of this component should be a subdomain of the domain returned by this method.

Returns:

The XMPP domain name, or null if this component has not been initialized yet.

getJID

public JID getJID()

Returns the XMPP address / Jabber ID (JID) of this component.

Returns:

The JID of this component, or null if this component has not been initialized yet.

discoInfoIdentityCategory

protected java.lang.String discoInfoIdentityCategory()

Returns the category of the Service Discovery Identity of this component (this implementation will only hold exactly one Identity for the component).

The default Category of a component, which is used if this method is not overridden, is 'component'.

Returns:

the category of the Service Discovery Identity of this component.

See Also:

official * Service Discovery Identities registry< /a>

discoInfoIdentityCategoryType

protected java.lang.String discoInfoIdentityCategoryType()

Returns the type of the Service Discovery Identity of this component (this implementation will only hold exactly one Identity for the component).

The default Category type of a component, which is used if this method is not overridden, is 'generic'.

Returns:

the type of the Service Discovery Identity of this component.

See Also:

official Service Discovery Identities registry

discoInfoFeatureNamespaces

protected java.lang.String[] discoInfoFeatureNamespaces()

This method returns a String array that should contain all namespaces of features that this component offers. The result of this method will be included in Service Discovery responses.

Note that the features that are returned by this method should also be implemented in either #handleIQGet() and/or #handleIQSet() methods. Also note that the default namespaces for service discovery should not be returned by this method.

The default implementation of this method returns an empty array. Override this method to include new namespaces.

Returns:

Namespaces of all features provided by this Component

handleMessage

protected void handleMessage(Message message)

Override this method to handle the Message stanzas that are received by the component. If you do not override this method, the stanzas are ignored.

Parameters:

message - The Message stanza that was received by this component.

handlePresence

protected void handlePresence(Presence presence)

Override this method to handle the Presence stanzas that are received by the component. If you do not override this method, the stanzas are ignored.

Parameters:

presence - The Presence stanza that was received by this component.

servesLocalUsersOnly

public boolean servesLocalUsersOnly()

Checks if the component can only be used by users of the XMPP domain that the component has registered to. If this method returns true, this will happen:

• Messages and Presence stanzas are silently ignored.
• IQ stanza's of type result and error are silently ignored.
• IQ stanza's of type get or set are responded to with a IQ error response, type 'cancel', condition 'not-allowed'.

  Note that by default, this method returns false. You can override this method to change the behavior.

  Returns:

  true if this component serves local users only, false otherwise.

shutdown

public final void shutdown()

Default implementation of the shutdown() method of the Component interface.

Specified by:

shutdown in interface Component

send

protected void send(Packet packet)

Helper method to send packets.

Parameters:

packet - The packet to send.

preComponentShutdown

public void preComponentShutdown()

This method gets called as part of the Component shutdown routine. This method gets called before the other shutdown methods get executed. This enables extending classes to initiate a cleanup before the component gets completely shut down.

postComponentShutdown

public void postComponentShutdown()

This method gets called as part of the Component shutdown routine. This method gets called after the other shutdown methods got executed. This enables extending classes to finish cleaning up after all other cleanup has been performed.

start

public void start()

Default implementation of the start() method of the Component interface. Unless overridden, this method doesn't do anything. We get called once for each host that we connect to, so we have to take care to avoid double initialization.

Specified by:

start in interface Component

preComponentStart

public void preComponentStart()

This method gets called as part of the Component 'start' routine. This method gets called before the other 'start' methods get executed. This enables extending classes to initialize resources before the component gets completely started. This method is called once for each host that we connect to, so we have to take care to avoid double initialization.

postComponentStart

public void postComponentStart()

This method gets called as part of the Component 'start' routine. This method gets called after the other 'start' methods got executed. This enables extending classes to finish initializing resources after all other resources has been initialized. This method is called once for each host that we connect to, so we have to take care to avoid double initialization.