1 /*------------------------------------------------------------------------------
2 Name: xmlBlaster.idl
3 Project: xmlBlaster.org
4 Task: Server interface
5 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
6 Comment: String arguments should never be null, use "" instead
7 Compile: JacORB Java 1.2:
8 $JacORB_HOME/bin/idl -p org.xmlBlaster -d ${XMLBLASTER_HOME}/src/java xmlBlaster.idl
9 VisiBroker (no JacORB should be in CLASSPATH) Java 1.2:
10 ${VBROKER_PATH}/bin/idl2java -root_dir ${XMLBLASTER_HOME}/src/java xmlBlaster.idl
11 MICO C++:
12 $CORBACPP_HOME/bin/idl --poa --no-boa xmlBlaster.idl
13 COPE Perl:
14 idl2perl -imp xmlBlaster.idl
15 Author: xmlBlaster@marcelruff.info
16 Version: $Id: xmlBlaster.idl 15026 2006-04-10 16:56:35Z ruff $
17 ------------------------------------------------------------------------------*/
18
19 #ifndef _xmlBlaster_IDL_
20 #define _xmlBlaster_IDL_
21
22
23 #pragma prefix "org.xmlBlaster.protocol.corba"
24
25
26 /**
27 * Declaration of common types
28 */
29 module serverIdl
30 {
31 //This ifdef works with jacorb, but is not added to build.xml for C++ idl compilers
32 //#ifdef XBL_IDL_WSTRING
33 // Works fine with Javaclient -> xmlBlaster
34 // but failed with MicoC++Client -> xmlBlaster, the received ConnectQos wstring was empty, is not yet resolved
35 // typedef wstring XmlType;
36 //#else
37 typedef string XmlType;
38 //#endif
39 typedef sequence<XmlType> XmlTypeArr;
40
41 typedef sequence<octet> ContentType;
42
43 /**
44 * This contains all informations about a Message and the Message itself.
45 *
46 * @param xmlKey Unique message key with index attributes
47 * @param content The data itself (XML data, java objects, jpeg pictures ...)
48 * @param qos The Quality of Service hints to control behaviour
49 * @see onMessage() method in JMS
50 */
51 struct MessageUnit {
52 XmlType xmlKey;
53 ContentType content;
54 XmlType qos;
55 };
56 typedef sequence<MessageUnit> MessageUnitArr;
57
58
59 /**
60 * Exception class for xmlBlaster interface
61 */
62 exception XmlBlasterException
63 {
64 string errorCodeStr;
65 string node;
66 string location;
67 string lang;
68 string message;
69 string versionInfo;
70 string timestampStr;
71 string stackTrace;
72 string embeddedMessage;
73 string transactionInfo;
74 string reserved;
75 // TODO: boolean isServerSide;
76 };
77
78 }; // org::xmlBlaster::protocol::corba::serverIdl
79
80
81
82
83 /**
84 * Declaration of the client Callback interface.
85 * <br />
86 * This interface must be implemented by the client.
87 * <br />
88 * You have to provide three methods: update(), updateOneway() and ping()
89 */
90 module clientIdl
91 {
92 /**
93 * This interface needs to be implemented by the clients.
94 * <p>
95 * The IOR of this BlasterCallback has to be passed initially to the
96 * xmlBlaster using the connect() method
97 */
98 interface BlasterCallback
99 {
100 /**
101 * This update is invoked when the server calls back to the client.
102 *
103 * @param sessionId To identify server (authentication)
104 * @param msgUnit Contains a sequence of 1 - n MessageUnit structs
105 * @return For every message "<qos><state id='OK'/></qos>"
106 * If some messages failed: "<qos><state id='ERROR'/></qos>"
107 * @exception On severe problem or on authentication deny
108 * an XmlBlasterException is thrown, all messages
109 * of this array are treated as lost
110 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.update.html" target="others">the interface.update requirement</a>
111 */
112 serverIdl::XmlTypeArr update(in string sessionId, in serverIdl::MessageUnitArr msgUnitArr)
113 raises(serverIdl::XmlBlasterException);
114
115 /**
116 * This update is invoked when the server calls back to the client.
117 *
118 * The oneway variant may be used for better performance,
119 * it is not returning a value (no application level ACK).
120 *
121 * @param sessionId To identify server
122 * @param msgUnit Contains a sequence of 1 - n MessageUnit structs
123 */
124 oneway void updateOneway(in string sessionId, in serverIdl::MessageUnitArr msgUnitArr);
125
126 /**
127 * Ping to check if the callback server is alive.
128 * This ping checks the availability on the application level.
129 * @param qos Currently an empty string ""
130 * @return Currently an empty string ""
131 */
132 string ping(in string qos);
133 };
134
135 }; // org::xmlBlaster::protocol::corba::clientIdl
136
137
138
139 /**
140 * The xmlBlaster interface
141 */
142 module serverIdl
143 {
144 /**
145 * This is an easy to use, message based, communication middleware interface.
146 *
147 * It allows event-driven instant communication between separate modules.
148 *
149 * COMMENTS:
150 * It is generic to avoid future changes to the IDL.
151 *
152 * This server uses the benefits of both technologies XML and CORBA.
153 *
154 * It is a compromise between compile time type checking (CORBA)
155 * and runtime type checking (XML).
156 *
157 * Runtime checking allows easier maintenance and migration to newer
158 * xmlBlaster Versions, compile time checking of invariant interfaces
159 * allows enhanced performance and early error checking.
160 *
161 * Authentication and Authorization is supported with the separate
162 * interface AuthServer.
163 *
164 * The <key oid=""> strings have to be handled in a hierarchical manner to avoid
165 * namespace conflicts or may be generated (as number) by the xmlBlaster-server.
166 *
167 * BENEFITS:
168 * xmlBlaster allows instant communication between different uncoupled modules
169 * spread over the Internet (publish / subscriber and point to point framework).
170 *
171 * For example:
172 * - Clipboard functionality to store permanent the clipboard entries
173 * of many clients
174 * - Task handling
175 * This feature allows automatic notification, when a task
176 * for a special user is available.
177 * - Inter client communication (chat rooms, graphic rooms etc.)
178 * - Broadcasts over well known attribute-keys
179 * or by notifying all known client-callback interfaces
180 * - email like instant notifications
181 * - inter process 'model/view/controller' paradigm
182 * - synchronize html with embedded applets over the server
183 * - data and message transfer between subsystems
184 * - controller support functionality like subsystem-alive slots,
185 * start and stop events etc.
186 * - configuration attributes with auto-notification
187 * - Central logging facility for client/server systems
188 * - Radar tracking systems
189 *
190 * RELATED DESIGN PATTERNS:
191 * @see JMS - Java Message Service, http://java.sun.com/products/jms/
192 * @see JMQ - A reference implementation of JMS, http://www.sun.com/workshop/jmq/
193 * @see JNDI - Java Naming & Directory Interface, www.javasoft.com/products/jndi
194 * @see Observer Pattern, Gamma et.al
195 * @see CORBA Property Service, http://www.omg.org
196 * @see CORBA Notification Service ftp://ftp.omg.org/pub/docs/telecom/98-01-01.pdf
197 * @see CORBA Event Service (push/pull concepts), http://www.omg.org
198 * @see CORBA Design Patterns, Mowbray Thomas J. et al. 'Dynamic Attributes'
199 * @see CORBA Messaging Service
200 * @see Addressless message-event-middleware pattern
201 */
202 interface Server
203 {
204 /**
205 * Asynchronous read-access method.
206 *
207 * The results are returned to the
208 * Client-Callback interface via the update() method.
209 * You need to implement the method BlasterCallback.update()
210 * This is the push modus.
211 *
212 * @param xmlKey Key with attributes allowing XPath or EXACT selection<br />
213 * See xmlBlaster/src/dtd/XmlKey.xml for a description
214 * @param qos Quality of Service, flags to control subscription<br>
215 * See xmlBlaster/src/dtd/XmlQoS.xml for a description
216 * @return oid The subscription ID of your subscribed message(s)<br>
217 * If you subscribed using a query, the subscription ID of this<br>
218 * query handling object is returned.<br>
219 * You should use this subId if you wish to unSubscribe()<br>
220 * If no match is found, an empty string "" is returned.
221 *
222 * @see addListener in Java event model
223 * @see addObserver in Java observer pattern
224 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.subscribe.html" target="others">the interface.subscribe requirement</a>
225 */
226 XmlType subscribe(in XmlType xmlKey, in XmlType qos)
227 raises(XmlBlasterException);
228
229
230 /**
231 * Synchronous read-access methods
232 * This is the pull modus.
233 *
234 * @param xmlKey Key with attributes allowing XPath or EXACT selection<br />
235 * See xmlBlaster/src/dtd/XmlKey.xml for a description
236 * @param qos Quality of Service, flags to control get()<br>
237 * See xmlBlaster/src/dtd/XmlQoS.xml for a description
238 * @return Contains a sequence of 0 - n MessageUnit structs with its qos infos
239 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.get.html" target="others">the interface.get requirement</a>
240 */
241 MessageUnitArr get(in XmlType xmlKey, in XmlType qos)
242 raises(XmlBlasterException);
243
244
245 /**
246 * if a key was subscribed forever, you can cancel your
247 * subscription with following method
248 *
249 * @param xmlKey Key contains the subscription ID returned from subscribe()<br />
250 * See xmlBlaster/src/dtd/XmlKey.xml for a description
251 * @param qos Quality of Service, flags to control canceling of a subscription<br>
252 * See xmlBlaster/src/dtd/XmlQoS.xml for a description
253 * @return XML string array with the subscription id's in XML markup
254 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.unSubscribe.html" target="others">the interface.unSubscribe requirement</a>
255 */
256 XmlTypeArr unSubscribe(in XmlType xmlKey, in XmlType qos)
257 raises(XmlBlasterException);
258
259
260 /**
261 * Write-Access Method.
262 * This triggers the method update() if subscribed (observed) by somebody
263 * or if addressed as Point-to-Point (PtP).
264 * If the given key oid doesn't exist, it will be automatically added,
265 * so this covers the SQL'ish INSERT and UPDATE.<p>
266 *
267 * @param msgUnit Contains a MessageUnit struct
268 * @return String with the key oid of the msgUnit
269 * If you let the oid be generated, you need this information
270 * for further publishing to the same MessageUnit<br>
271 * Rejected Messages will contain an empty string ""
272 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.publish.html" target="others">the interface.publish requirement</a>
273 */
274 XmlType publish(in MessageUnit msgUnit)
275 raises(XmlBlasterException);
276
277 /**
278 * Write-Access Method
279 * This triggers the method update() if observed by somebody
280 * If the given key doesn't exist, it will be automatically added,
281 * so this covers the SQL'ish INSERT and UPDATE.
282 *
283 * For performance or transaction reasons, you can send a whole array
284 * of MessageUnit with one invocation of publishArr()
285 *
286 * @param msgUnit Contains a sequence of 1 - n MessageUnit structs
287 * @return String array with the key oid's, corresponding to the index
288 * of msgUnitArr<br>
289 * If you let the oid be generated, you need this information
290 * for further publishing to the same MessageUnit array<br>
291 * Rejected Messages will contain an empty string ""
292 * @exception On severe problem an XmlBlasterException is thrown, all messages
293 * of this array should be treated as lost
294 */
295 XmlTypeArr publishArr(in MessageUnitArr msgUnitArr)
296 raises(XmlBlasterException);
297
298 /**
299 * Publish a message to the server.
300 *
301 * The oneway variant may be used for better performance,
302 * it is not returning a value (no application level ACK).
303 *
304 * For performance reasons, you can send a whole array
305 * of MessageUnit with one Invocation of publishOneway()
306 *
307 * @param msgUnit Contains a sequence of 1 - n MessageUnit structs
308 */
309 oneway void publishOneway(in MessageUnitArr msgUnitArr);
310
311 /**
312 * Erase a MessageUnit
313 * @return String array with the key oid's which are deleted
314 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.erase.html" target="others">the interface.erase requirement</a>
315 */
316 XmlTypeArr erase(in XmlType xmlKey, in XmlType qos)
317 raises(XmlBlasterException);
318
319
320 /**
321 * Ping to check if xmlBlaster is alive.
322 * This ping checks the availability on the application level.
323 * @param qos Currently an empty string ""
324 * @return Currently an empty string ""
325 */
326 string ping(in string qos);
327
328 }; // interface server
329
330 }; // org::xmlBlaster::protocol::corba::serverIdl
331
332
333
334 /**
335 * The xmlBlaster authentication interface.
336 * <p>
337 * Use this interface to access via login() the xmlBlaster
338 * <p>
339 * The final authentication/authorization interace is not yet specified
340 */
341 module authenticateIdl
342 {
343 interface AuthServer
344 {
345 /**
346 * @deprecated Use connect() instead
347 */
348 serverIdl::Server login(in string loginName, in string passwd,
349 in serverIdl::XmlType qosClient)
350 raises (serverIdl::XmlBlasterException);
351
352 /**
353 * Initializes a new xmlBlaster session. (Successor of login( ... ); )
354 * <p>
355 * @param qos Quality of Service, flags for additional client
356 * information like client certificate (X.509), timeout etc.
357 * Typically it contains the IOR reference to the
358 * BlasterCallback interface or other protocol addresses
359 * like email or http URL
360 * @return qos information like sessionId, keys, ...
361 * @exception XmlBlasterException if the login fails
362 * @see xmlBlaster/src/dtd/XmlQoS.xml and dtd for qos examples
363 * @see ConnectQosSaxFactory.java Javadoc description
364 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.connect.html" target="others">the interface.connect requirement</a>
365 */
366 serverIdl::XmlType connect(in serverIdl::XmlType qos)
367 raises (serverIdl::XmlBlasterException);
368
369 /**
370 * @deprecated Use disconnect() instead
371 */
372 void logout(in serverIdl::Server xmlBlaster)
373 raises (serverIdl::XmlBlasterException);
374
375 /**
376 * Disconnects the client from the xmlBlaster and closes the session.
377 * <br>(Counterpart of connect( ... ); )
378 * <p>
379 * @param sessionId The server interface handle returned in the init qos.
380 * @param qos An optional signature etc.
381 */
382 void disconnect(in string sessionId, in serverIdl::XmlType qos)
383 raises (serverIdl::XmlBlasterException);
384
385 /**
386 * Ping to check if the authentication server is alive.
387 * This ping checks the availability on the application level.
388 * @param qos Currently an empty string ""
389 * @return Currently an empty string ""
390 */
391 string ping(in string qos);
392 };
393 }; // org::xmlBlaster::protocol::corba::authenticateIdl
394
395
396
397 #endif // _xmlBlaster_IDL_
syntax highlighted by Code2HTML, v. 0.9.1