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

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

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

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

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

Logout from xmlBlaster.

Parameters:

disconnectQos - The QoS or null

Throws:

XmlBlasterException

getProtocol

java.lang.String getProtocol()

Returns:

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

shutdown

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

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

boolean isLoggedIn()

ping

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

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

Throws:

XmlBlasterException

get

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

Throws:

XmlBlasterException

unSubscribe

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

Throws:

XmlBlasterException

publish

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

Parameters:

The - msgUnit which is encrypted if a security plugin is activated

Throws:

XmlBlasterException

publishOneway

void publishOneway(MsgUnitRaw[] msgUnitArr)
                   throws XmlBlasterException

Throws:

XmlBlasterException

publishArr

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

Throws:

XmlBlasterException

erase

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

Throws:

XmlBlasterException

registerProgressListener

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