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