org.xmpp.component
Class AbstractComponent

java.lang.Object
  extended by 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:

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:

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:


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.



Copyright © 2009-2010 Ignite Realtime. All Rights Reserved.