org.xmlBlaster.client.protocol
Interface I_XmlBlasterConnection

All Superinterfaces:

I_Plugin

All Known Implementing Classes:

CorbaConnection, EmailConnection, LocalConnection, RmiConnection, SocketConnection, XmlRpcConnection

public interface I_XmlBlasterConnection

extends I_Plugin

This is the client interface to xmlBlaster.

All protocol drivers are accessed through these methods. We need it to decouple the protocol specific stuff (like RemoteException from RMI or CORBA exceptions) from our java client code.

Note that you don't need this code, you can access xmlBlaster with your own lowlevel RMI or CORBA coding as well.

If you are interested in a failsafe client connection, consider using XmlBlasterAccess.java which implements some nice features.

The plugins which implement this interface do NOT need to be thread safe.

Author:

Marcel Ruff.

See Also:

XmlBlasterAccess

Method Summary

java.lang.String	connect(java.lang.String connectQos) Login and authenticate, the authentication schema is transported in the qos.
void	connectLowlevel(Address address) Initialize the driver and verify if the remote side is reachable on the low-level protocol layer.
boolean	disconnect(java.lang.String disconnectQos) Logout from xmlBlaster.
java.lang.String[]	erase(java.lang.String xmlKey, java.lang.String qos)
MsgUnitRaw[]	get(java.lang.String xmlKey, java.lang.String qos)
java.lang.String	getProtocol()
boolean	isLoggedIn()
java.lang.String	ping(java.lang.String qos) Ping the server on physical level and/or application level (see AvailabilityChecker).
java.lang.String	publish(MsgUnitRaw msgUnit)
java.lang.String[]	publishArr(MsgUnitRaw[] msgUnitArr)
void	publishOneway(MsgUnitRaw[] msgUnitArr)
I_ProgressListener	registerProgressListener(I_ProgressListener listener) Register a listener for to receive information about the progress of incoming data.
void	resetConnection() Reset the driver on problems.
void	setConnectReturnQos(ConnectReturnQos connectReturnQos) Pass the driver the decrypted and parsed ConnectReturnQos directly after a connect.
void	shutdown() Cleans up the resource.
java.lang.String	subscribe(java.lang.String xmlKey, java.lang.String qos)
java.lang.String[]	unSubscribe(java.lang.String xmlKey, java.lang.String qos)

Methods inherited from interface org.xmlBlaster.util.plugin.I_Plugin

getType, getVersion, init

Method Detail

connectLowlevel

public void connectLowlevel(Address address)
                     throws XmlBlasterException

Initialize the driver and verify if the remote side is reachable on the low-level protocol layer. Calling this method multiple times will do noting if a low level connection is available.

Parameters:

address - Contains the remote address, e.g. the host and port where the remote server listens

Throws:

XmlBlasterException - ErrorCode.COMMUNICATION* if the server is not reachable, in this case we can poll for the server.
Other errors if for example a malformed address is passed, in this case we stop and give up.

connect

public java.lang.String connect(java.lang.String connectQos)
                         throws XmlBlasterException

Login and authenticate, the authentication schema is transported in the qos. You are allowed to call connect multiple times, for example if the physical connection is still OK or again OK and you need to re-configure.

Parameters:

connectQos - The authentication and other informations (ConnectQos encrypted)

Returns:

ConnectReturnQos XML string

Throws:

XmlBlasterException

setConnectReturnQos

public void setConnectReturnQos(ConnectReturnQos connectReturnQos)
                         throws XmlBlasterException

Pass the driver the decrypted and parsed ConnectReturnQos directly after a connect. Some driver take the secretSessionId from it or a returned remote address

Throws:

XmlBlasterException

disconnect

public boolean disconnect(java.lang.String disconnectQos)
                   throws XmlBlasterException

Logout from xmlBlaster.

Parameters:

disconnectQos - The QoS or null

Throws:

XmlBlasterException

getProtocol

public java.lang.String getProtocol()

Returns:

The connection protocol name "IOR" or "RMI" etc.

shutdown

public void shutdown()
              throws XmlBlasterException

Description copied from interface: I_Plugin

Cleans up the resource.

Specified by:

shutdown in interface I_Plugin

Throws:

XmlBlasterException - if an exception occurs. The exception is handled by the RunLevelManager depending on how the plugin has been configured with the action:

<action do='STOP' onShutdownRunlevel='2' sequence='5' onFail='resource.configuration.pluginFailed'> If onFail is defined to something, the RunLevelManager will stop.

resetConnection

public void resetConnection()

Reset the driver on problems. This method is called by the dispatcher framework on transition to POLLING, the protocol plugin must be able to establish a new connection after this call with a call to connectLowLevel().

isLoggedIn

public boolean isLoggedIn()

ping

public java.lang.String ping(java.lang.String qos)
                      throws XmlBlasterException

Ping the server on physical level and/or application level (see AvailabilityChecker). This ping must be successful if the client can reach the server, with or without authentication (with or without connect()).

Returns:

The StatusQosData string

Throws:

XmlBlasterException

subscribe

public java.lang.String subscribe(java.lang.String xmlKey,
                                  java.lang.String qos)
                           throws XmlBlasterException

Throws:

XmlBlasterException

get

public MsgUnitRaw[] get(java.lang.String xmlKey,
                        java.lang.String qos)
                 throws XmlBlasterException

Throws:

XmlBlasterException

unSubscribe

public java.lang.String[] unSubscribe(java.lang.String xmlKey,
                                      java.lang.String qos)
                               throws XmlBlasterException

Throws:

XmlBlasterException

publish

public java.lang.String publish(MsgUnitRaw msgUnit)
                         throws XmlBlasterException

Throws:

XmlBlasterException

publishOneway

public void publishOneway(MsgUnitRaw[] msgUnitArr)
                   throws XmlBlasterException

Throws:

XmlBlasterException

publishArr

public java.lang.String[] publishArr(MsgUnitRaw[] msgUnitArr)
                              throws XmlBlasterException

Throws:

XmlBlasterException

erase

public java.lang.String[] erase(java.lang.String xmlKey,
                                java.lang.String qos)
                         throws XmlBlasterException

Throws:

XmlBlasterException

registerProgressListener

public I_ProgressListener registerProgressListener(I_ProgressListener listener)

Register a listener for to receive information about the progress of incoming data. Only one listener is supported, the last call overwrites older calls.

Parameters:

listener - Your listener, pass 0 to unregister.

Returns:

The previously registered listener or 0