001: /**
002: * Copyright (C) 2004-2007 Jive Software. All rights reserved.
003: *
004: * This software is published under the terms of the GNU Public License (GPL),
005: * a copy of which is included in this distribution.
006: */package org.xmpp.component;
007:
008: import org.jivesoftware.openfire.IQResultListener;
009: import org.xmpp.packet.IQ;
010: import org.xmpp.packet.Packet;
011:
012: /**
013: * Manages components.
014: *
015: * @see Component
016: * @author Matt Tucker
017: */
018: public interface ComponentManager {
019:
020: /**
021: * Adds a component. The {@link Component#initialize(org.xmpp.packet.JID, ComponentManager)}
022: * method will be called on the component. The subdomain specifies the address of
023: * the component on a server. For example, if the subdomain is "test" and the XMPP
024: * server is at "example.com", then the component's address would be "test.example.com".
025: *
026: * @param subdomain the subdomain of the component's address.
027: * @param component the component.
028: */
029: public void addComponent(String subdomain, Component component)
030: throws ComponentException;
031:
032: /**
033: * Removes a component. The {@link Component#shutdown} method will be called on the
034: * component.
035: *
036: * @param subdomain the subdomain of the component's address.
037: */
038: public void removeComponent(String subdomain)
039: throws ComponentException;
040:
041: /**
042: * Sends a packet to the XMPP server. The "from" value of the packet must not be null.
043: * An <tt>IllegalArgumentException</tt> will be thrown when the "from" value is null.<p>
044: *
045: * Components are trusted by the server and may use any value in from address. Usually
046: * the from address uses the component's address as the domain but this is not required.
047: *
048: * @param component the component sending the packet.
049: * @param packet the packet to send.
050: */
051: public void sendPacket(Component component, Packet packet)
052: throws ComponentException;
053:
054: /**
055: * Sends an IQ packet to the XMPP server and waits to get an IQ of type result or error.
056: * The "from" value of the packet must not be null. An <tt>IllegalArgumentException</tt>
057: * will be thrown when the "from" value is null.<p>
058: *
059: * If no answer is received from the server before the specified timeout then an IQ
060: * of type error will be returned.
061: *
062: * Components are trusted by the server and may use any value in from address. Usually
063: * the from address uses the component's address as the domain but this is not required.
064: *
065: * @param component the component sending the packet.
066: * @param packet the IQ packet to send.
067: * @param timeout the number of milliseconds to wait before returning an IQ error.
068: * @return the answer sent by the server. The answer could be an IQ of type result or
069: * error.
070: */
071: public IQ query(Component component, IQ packet, int timeout)
072: throws ComponentException;
073:
074: /**
075: * Sends an IQ packet to the server and returns immediately. The specified IQResultListener
076: * will be invoked when an answer is received.
077: *
078: * @param component the component sending the packet.
079: * @param packet the IQ packet to send.
080: * @param listener the listener that will be invoked when an answer is received.
081: */
082: public void query(Component component, IQ packet,
083: IQResultListener listener) throws ComponentException;
084:
085: /**
086: * Returns a property value specified by name. Properties can be used by
087: * components to store configuration data. It is recommended that each
088: * component qualify property names to prevent overlap. For example a
089: * component that broadcasts messages to groups of users, might prepend
090: * all property names it uses with "broadcast.".
091: *
092: * @param name the property name.
093: * @return the property value.
094: */
095: public String getProperty(String name);
096:
097: /**
098: * Sets a property value. Properties can be used by components to
099: * store configuration data. It is recommended that each component
100: * qualify property names to prevent overlap. For example a component
101: * that broadcasts messages to groups of users, might prepend all
102: * property names it uses with "broadcast.".
103: *
104: * @param name the property name.
105: * @param value the property value.
106: */
107: public void setProperty(String name, String value);
108:
109: /**
110: * Returns the domain of the XMPP server. The domain name may be the IP address or the host
111: * name.
112: *
113: * @return the domain of the XMPP server.
114: */
115: public String getServerName();
116:
117: /**
118: * Returns true if components managed by this component manager are external
119: * components connected to the server over a network connection. Otherwise,
120: * the components are internal to the server.
121: *
122: * @return true if the managed components are external components.
123: */
124: public boolean isExternalMode();
125:
126: /**
127: * Returns a Log instance, which can be used by components for logging error,
128: * warning, info, and debug messages.
129: *
130: * @return a Log instance.
131: */
132: public Log getLog();
133: }
|