1 /*------------------------------------------------------------------------------
2 Name: I_XmlBlasterConnection.java
3 Project: xmlBlaster.org
4 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
5 Comment: Native Interface to xmlBlaster
6 Author: xmlBlaster@marcelruff.info
7 ------------------------------------------------------------------------------*/
8 package org.xmlBlaster.client.protocol;
9
10 import org.xmlBlaster.client.qos.ConnectReturnQos;
11 import org.xmlBlaster.util.XmlBlasterException;
12 import org.xmlBlaster.util.plugin.I_Plugin;
13 import org.xmlBlaster.util.qos.address.Address;
14 import org.xmlBlaster.util.xbformat.I_ProgressListener;
15
16
17 /**
18 * This is the client interface to xmlBlaster.
19 * <p />
20 * All protocol drivers are accessed through these methods.
21 * We need it to decouple the protocol specific stuff
22 * (like RemoteException from RMI or CORBA exceptions) from
23 * our java client code.
24 * <p />
25 * Note that you don't need this code, you can access xmlBlaster
26 * with your own lowlevel RMI or CORBA coding as well.
27 * <p />
28 * If you are interested in a failsafe client connection, consider
29 * using XmlBlasterAccess.java which implements some nice features.
30 * <p>
31 * The plugins which implement this interface do NOT need to be thread safe.
32 * </p>
33 *
34 * @see org.xmlBlaster.client.XmlBlasterAccess
35 *
36 * @author <a href="mailto:xmlBlaster@marcelruff.info">Marcel Ruff</a>.
37 */
38 public interface I_XmlBlasterConnection extends I_Plugin
39 {
40 /**
41 * Initialize the driver and verify if the remote side is reachable on the low-level protocol layer.
42 * Calling this method multiple times will do noting if a low level connection is available.
43 * @param address Contains the remote address,
44 * e.g. the host and port where the remote server listens
45 * @exception XmlBlasterException ErrorCode.COMMUNICATION* if the server is not reachable,
46 * in this case we can poll for the server.<br />
47 * Other errors if for example a malformed address is passed, in this case we stop
48 * and give up.
49 */
50 public void connectLowlevel(Address address) throws XmlBlasterException;
51
52 /**
53 * Login and authenticate, the authentication schema is transported in the qos.
54 * You are allowed to call connect multiple times, for example if the physical connection
55 * is still OK or again OK and you need to re-configure.
56 * @param connectQos The authentication and other informations (ConnectQos encrypted)
57 * @return ConnectReturnQos XML string
58 */
59 public String connect(String connectQos) throws XmlBlasterException;
60
61 /**
62 * Pass the driver the decrypted and parsed ConnectReturnQos directly after a connect.
63 * Some driver take the secretSessionId from it or a returned remote address
64 */
65 public void setConnectReturnQos(ConnectReturnQos connectReturnQos) throws XmlBlasterException;
66
67 /**
68 * Logout from xmlBlaster.
69 * @param disconnectQos The QoS or null
70 */
71 public boolean disconnect(String disconnectQos) throws XmlBlasterException;
72
73 // Could make sense to the SOCKET driver, returns new SocketCallbackImpl
74 //public I_CallbackServer getCbServerInstance() throws XmlBlasterException;
75
76 /**
77 * @return The connection protocol name "IOR" or "RMI" etc.
78 */
79 public String getProtocol();
80
81 public void shutdown() throws XmlBlasterException;
82
83 /**
84 * Reset the driver on problems.
85 * This method is called by the dispatcher framework on transition to POLLING,
86 * the protocol plugin must be able to establish a new connection after this call
87 * with a call to connectLowLevel().
88 */
89 public void resetConnection();
90
91 public boolean isLoggedIn();
92
93 /**
94 * Ping the server on physical level and/or application level (see AvailabilityChecker).
95 * This ping must be successful if the client can reach the server,
96 * with or without authentication (with or without connect()).
97 * @return The StatusQosData string
98 */
99 public String ping(String qos) throws XmlBlasterException;
100
101 public java.lang.String subscribe(java.lang.String xmlKey, java.lang.String qos) throws XmlBlasterException;
102
103 public org.xmlBlaster.util.MsgUnitRaw[] get(java.lang.String xmlKey, java.lang.String qos) throws XmlBlasterException;
104
105 public String[] unSubscribe(java.lang.String xmlKey, java.lang.String qos) throws XmlBlasterException;
106
107 /**
108 * @param The msgUnit which is encrypted if a security plugin is activated
109 */
110 public String publish(org.xmlBlaster.util.MsgUnitRaw msgUnit) throws XmlBlasterException;
111
112 public void publishOneway(org.xmlBlaster.util.MsgUnitRaw [] msgUnitArr) throws XmlBlasterException;
113
114 public String[] publishArr(org.xmlBlaster.util.MsgUnitRaw[] msgUnitArr) throws XmlBlasterException;
115
116 public java.lang.String[] erase(java.lang.String xmlKey, java.lang.String qos) throws XmlBlasterException;
117
118 /**
119 * Register a listener for to receive information about the progress of incoming data.
120 * Only one listener is supported, the last call overwrites older calls.
121 * @param listener Your listener, pass 0 to unregister.
122 * @return The previously registered listener or 0
123 */
124 public I_ProgressListener registerProgressListener(I_ProgressListener listener);
125
126 }
syntax highlighted by Code2HTML, v. 0.9.1